on-api/on-api

Open Networks API

Open Networks API (ON-API) is a communication protocol which enables automation of processes between Service Providers (SP) and Service Operators (SO). This is done via a standardized machine-to-machine interface (REST api) specification with requirements of how data should be processed and presented. The main purpose of the API is to provide automated communication as an alternative to manual processes.

The specification includes support for areas such as:

• Addresses
• Orders
• Subscriptions
• Tickets
• Troubleshooting
• Invoicing

In summary, the API is a specification which defines how data shall be formatted and transmitted between parties, for a machine to be able to interpret the data from a set of rules, as opposed to human interpretation.
An example is the manual order process, where the Service Provider must first activate a service in an internal system, followed by either requesting an external activation by e-mail or in an external system. This process is replaced by a machine on each end that will automatically interpret the data in an order and perform the requested operation.

Versions

• ON-API 2.6.0
• ON-API 2.5.0
• ON-API 2.4.0
• ON-API 2.3.1

on-api's Issues

Description on status on Tickets

There's no description in the documentation on status in the service Tickets. Suggestion:

Status	Description
CREATED	Ticket is created
IN_PROGRESS_CO	CO is working on the ticket
IN_PROGRESS_SP	SP is working on the ticket
CLOSED	Ticket is closed

Orders: missing `operationalState` enum value for scheduled subscriptions

The operationalState field on a subscription can only have two values (ACTIVATED or SUSPENDED) according to the spec. So if a SP orders a service with a future requestedDateTime then neither of the two possible operationalState values correctly represents the state of the service as it's not really activated yet, only "scheduled" for activation.

Or is this by design and intention? I.e. should the operationalState also be ACTIVATED in the case of a future requestedDateTime? If so I think the documentation should be updated with a note on this, and if not we should add an additional possible operationalState like SCHEDULED or similar.

What do you think?

Order: Add CustomerData to order

Suggested Labels: endpoint/order

Background:
CO's that still send own invoices and therefore wants customer data from the SP are currently limited to and stuck with PI-api 2.2.0 (or maybe a modified 2.3.0).

Suggested solution:
Allow customer data to be sent with an activation. The data should be optional in the request as not to break any implementation that do not use customer data. It is up to the CO to respond with a failure if the required data is missing.

Example of structure adapted from https://github.com/ComHem/oss-provider-interface-api/blob/master/docs/provider_api_2.2/service_activation.md#orderl%C3%A4ggning-exempel-aktivering:
""customer"": {
""firstName"": ""Kalle"",
""lastName"": ""Anka"",
""socialSecurityNumber"": ""192012317777"",
""email"": ""[email protected]"",
""phone"": ""031-119119"",
""mobilePhone"": """",
""street"": ""Testvägen 100"",
""zipCode"": ""10000"",
""city"": ""Ankeborg""
}"

Support for using spTicketReference instead of spReference in SP Contacts

In my opinion, it should be possible to use spTicketReference instead of spReference in SP Contacts to limit the transaction of personal data, limited to if there is an active SP trouble ticket that is previously shared though tickets API or other manual process. The benefit of this is limiting the transaction of personal data to the scenario where to CO needs to send a technician to the end customer.

Accesses: Add accessStates for migrations to Access endpoint

I propose that we add the following access sates:
INMIGRATION
OUTMIGRATION
Addresses in these states are normally not allowing orders, since they either are not connected or is "frozen" for migration away to a new CO/NO.

For the dates proposed in
#78
INMIGRATION uses StartDate - as the date when the address will be available
OUTMIGRATION uses EndDate - as the date when the address will be unavailable for services

Reducing memory load/response body sizes

In our implementation of ON-API we're having some issues with supplying millions or more access in the /accesses endpoint. We're shoving 100+ Mbs in such responses, and at times experiencing time outs in our infrastructure when clients ask for all accesses.

Is it sensible to have the specification include paging/offset/limit functionality?

Implementation suggestions

• GitHub's own REST API uses per_page and page query params
• Spotify developer REST API uses limit and offset query params

Access: PremisesType - More enumerations needed

With the future implementation of priceGroup the following may be relevant to add.

premisesType:
There is a a need to add two more enumerations for Holiday homes (Fritidsboenden).
Example HOLIDAY_HOUSE and HOLIDAY_MDU_APARTMENT.

In certain CO there is a separation of prices and/or technical services depending if the access is a residential, company or holiday house/apartment. For example you could have a "base" internet service (say 2/2 Mbit/s) for IoT that is active all year but the owner/renter could upgrade to a faster one for 1-x days and then it returns to the base. This is only available to Holiday homes.
In other COs there are 3-day, 7-day or 14-day prepaid services that should only be allowed on certain accesses.

In order to "know" it might be necessary to introduce two or more new enums.

The priceGroup field only gives what price list a certain access belongs to but premisesType is still needed to differentiate the type of access; for example if it is a consumer access or a company access. But also residential houses vs holiday houses.

Time in disconnection date?

looked at the Accesses API and I find it a bit strange that time is not included in the connection & disconnection:

    "services": [
      {
        "service": "BB-10-10",
        "connection": "2019-04-19",
        "available": "NO",
        "disconnection": "2021-04-19"
      }

When is "2018-12-31"? Sometime between 00:01 and 23:59? Wouldn't it make sense to add time so that a new TL known when it's OK to place an order? I suggest using ISO 8601, I.e. 2018-08-20T14:09:23Z.

Use key name within curly brackets in URLs rather than example values

We currently have a mix of example values and key names within curly brackets for example

GET /onapi/2.4/accesses/STTA0001 HTTP/1.1

and

GET /api/2.4/tickets/{coTicketReference}

I propose we replace all instances to use the second notation type making it clear what value is expected in URLs

Implementation status ON-API (all versions)

This issue is used to report the implementation status of each endpoint for all versions of ON-API. Please apply implementation status for the company or companies that you represent, according to template below.

Accepted values are: Yes/No/ETA (eg. Q3 2020)

Version 2.3.1

Company:
Availability:
Feasibility:
Service Activation:
Link status:
Access customer info:
CO Active services:

Version 2.4.0

Company:
Accesses:
Orders:
Tickets:
Technical information:
Contacts:
Subscriptions:
Invoice Specification:

As an alternative to commenting in this issue, parties are allowed to commit implementation status of the company or companies that you represent directly to README on the main repo.

Invoice specification

Please leave your feedback for the invoice specification in this issue.

Describe clearly which columns you wish to leave feedback on. If you want to add new columns, describe the column that you want to add, and what purpose it will serve.

Link to invoice specification: https://github.com/on-api/on-api/files/4488960/faktura-specifikation-2018-02.xlsx

Accesses: (Re-)Add CoID to Accesses endpoint

In the original address specification from PI-API we had a mandatory field identifying the CO.
"coID - Unik identifierare för varje KO. "
It was removed in ON-API 2.4

I suggest we bring that field back to support co-operations between several networks or several CO brands in one system.
Otherwise such entities will be force to use population or other fields to distinguish between themselves.

Accesses: Rename accessState HOMESPASSED to PASSED

It might no be a home.
It is certainly not many homeS.

Why do we have two endpoints for order (order & orderevents)?

Why do we have two endpoints for order (order & orderevents)? Shouldn't this be handled with GET / POST? I guess some kind of event lifecycle is needed?

Example on lifecycle from TMF Service Ordering API:

Missing example for RESUME in orders.md

https://github.com/on-api/on-api/blob/master/2.4.0/spec/orders.md

Disruptions API

API to manage disruptions in SP or CO:s network. (Copied from old google sheets list)

Technical working group

The technical working group is an open group consisting of representatives from service providers, communication operators and system integrators.

The group is responsible for, based on requirements from the working group and steering group,

• technical maintenance of repositories and specifications
• continuous maintenance of work spaces

To become a member of the technical working group, simply comment below that you want to be an active member. If you want to be a member but can't contribute right now, comment below that you want to become an inactive member.

dhcpIdentifier is missing lookup endpoint

Since option82 was replaced by dhcpIdentifier, shouldn't it also have a lookup endpoint similar to option82? Something for 2.6?

/onapi/2.6/dhcpIdentifier/

Product API

API to manage products available for SP from CO. (Copied from old google sheets list)

Suggestion to Technical info and v.2.6

Would be great if it was possible to trigger a speed test to the KO/SOs CPE.

GET access/{accessId}/speedtest

Accesses: Add PTS UUID value

PTS (The Swedish Post and Telecom Authority) seems to have created its own list of Addresses over Sweden. Each address (note address, not access) have an UUID.
Every Access on the Address therefore share the same UUID.
This is needed for reporting purposes.

Propsal is to add this to the Accesses entity.

Access/Service/Subscriptions: Streamline the three endpoints

When getting all accesses from certain CO (especially larger ones) the response becomes very large. This is partly because they have a lot of accesses but more specifically that they tend to have a lot of services.

As an example from one CO a single access is over 12 000 characters minified with 100 services listed. Multiply with 100000+ accesses and everything stops working.

This will not scale, so my suggestion is that the "/accesses" endpoint DOES NOT contain services.
If there is a need to check services, then use the specific "/accesses/{accessID}".

If there IS a need to get all accesses AND have all services, then the API will probably need to implement a pageing structure to get batches of 100 or 1000 accesses.

Broken link to lantmäteriet in accesses spec

In https://github.com/on-api/on-api/blob/master/2.5.0/spec/accesses.md this link is broken (returns 404):

See lantmateriets guide (swedish) for more information on meter's address

Order: Change ID for all operations to spSubscriptionId

Note: This excludes "Activate a service" of course.

In 2.5.0 the required ID to deactivate, change, abuse block/unblock etc is subscriptionId. Example:
{
"operation": "DEACTIVATE",
"subscriptionId": "35738e19ab534dff9f9becb3a064a7d5",
"requestedDateTime": "2019-02-05T00:00:00Z"
}

This ID is set by the CO and is not controlled by the SP.

In many instances, this ID might change.
The CO may:

• do migrations internally
• manually remove and then add a service (for testing purposes)
• export the service to a new CO in a CO Change process

In all of the above cases, the subscriptionId is likely to change leaving the SP with incorrect data.

In the newly released Beta version of the CO Change process, spRef and spSubscriptionId should be migrated from a CO to another. Similarly the CO must maintain these values in any internal changes they make.

I therefore propose that subscriptionId is changed to be spSubscriptionId in ON-api 2.6.
This will also of course mean that spSubscriptionId must be mandatory and if a CO manually creates a service this must either be queried from the SP or the SP must be notified that they need to MODIFY the subscription.

There could also be a dual ID option where SP could supply either subscriptionId or spSubscriptionId but then it might be easier (recommended?) to implement two different operations?

Response issue for /accesses

Hi, Dev team,

If I call https://ispportal.seom.se/api/onapi/2.4/accesses on the Post man, I get the response with json data correctly.

By the way if I call the api in my backend(Node.js), in many cases I get the string instead of json.
I can get json data only 1 or 2 times if I call the api 100 times.

Here is my code.

const response = await axios({
    method: 'GET',
    responseType: 'json',
    headers: {
      'content-type': 'application/json'
    },
    auth: {
      username: process.env.OPEN_NETWORK_USER_ID,
      password: process.env.OPEN_NETWORK_USER_PASSWORD,
    },
    url,
    maxContentLength: 1000000000,
    maxBodyLength: 1000000000,
  });

I'd like you to check and let me know if I need to add more additional info in axios request.

Here is the screenshot what I can get.

OrderEvents vs Events

I am reading the specification again for the first time in a while. I noticed that on the "start page" of version 2.4 (https://github.com/on-api/on-api/tree/master/2.4.0) there is only a link to OrderEvents, not the "generic object events". But when I look at the files I found https://github.com/on-api/on-api/blob/master/2.4.0/spec/events.md file that defines the "generic object events".

Was the generic events removed from the final specification in favor of keeping it as it is in 2.3? Or are they both part of the specification? I am a bit confused and would appreciate a clarification.

Accesses / Feasability should include time in services/available

ISO-8601 RFC-3339 in UTC time zone should be included in services/available so that the customer does not need to wait one day for the new TL to place an order. Example:

    "service": "BB-100-100",
    "connection": "2013-10-12",
    "available": "2020-07-21T23:59:12Z",
    "disconnection": ""

Change required parameters

To my understanding, one of the required parameters to do changes on an already ordered service are subscriptionId. Why not only use spSubscriptionId instead as this should be given to the CO when the service is ordered?

Example on when subscriptionId is required:
https://github.com/on-api/on-api/blob/master/2.4.0/spec/orders.md#deactivate-a-service

In the SP endpoints no version is pressent in the example URLs

To be consistent the ON API version should be in the SP endpoints as well so when 2.6 arrives legacy implementations can be kept.

Example:
In https://github.com/on-api/on-api/blob/master/2.5.0/spec_sp/order.md#request the request should look like POST onapi/2.5/order/ HTTP/1.1

Example of patching order in 2.4 states it should use PUT

In the example for PATCH https://github.com/on-api/on-api/blob/master/2.4.0/spec/orders.md#patch it uses PUT, this should be PATCH to make sense.

Should we rename the Accesses API?

Should we maybe clarify the use of the Accesses API by changing the name to Service Qualification in v.2.5.0?

Description on the TMF645 Service Qualification API:
The Service Qualification API is one of the Pre-Ordering Management APIs. Its goal is to provide service availability at Customer location.

https://www.tmforum.org/resources/specification/tmf645-service-qualification-api-user-guide-v4-0/

Clearify if services is mandatory in accesses

In accesses the field services does not state if the field is mandatory or optional

Subscrptions Endpoint fetch single subscription

The /Subscriptions Endpoint would be enhanced if a single ref could be called.
For instance subscriptionId, spRefernce or spSubscriptionId.

Example
/Subscriptions/
/Subscriptions/spref/< spRefernce >
/Subscriptions/spSubref/< spSubscriptionId >

It would reduce the load on the server and make it easier to fetch a single sub.

Address specification

Please leave your feedback for the address specification in this issue.

Describe clearly which columns you wish to leave feedback on. If you want to add new columns, describe the column that you want to add, and what purpose it will serve.

Link to address specification: https://www.ssnf.org/globalassets/nat-i-varldsklass/rekommendationer/adressspecifikation-adresser-20150415.xlsx

Suggestions:

• Add MDU_COMMON to premisesType. This is already supported in ONAPI.
• servicesConnection should only support ISO-8601. YES could simply be replaced by past date, for example "2010-01-01".
• Add portCapacity so that we understand the maximum speed on the port without parsing the whole service list.
• Add cpeCapacity so that we understand if it is the CPE that limits the maximum speed available.
• Add serviceAgreement so that TL understands if the CO/NO supports the property network or not. YES/NO values.

accesses services/available

The available field used to be part of the availability only and not feasibility. Today its a required field at all times (at least what the spec says). Either it should be removed from the first example and marked as "Available with single access", if the spec is incorrect, or at least allow empty string like the services/disconnection if the KO is unable to provide this value.

Accesses: Removal of four fields

The Address and Invoice specification group wants to know if any of these four fields are in use anywhere or if they can be removed from the specification:

• coNetworkAgreement
• coFiberConverter
• coCpeSwitch
• coCpeRouter

Accesses: Add priceGroup field

Suggested Labels: endpoint/accesses

Background:
It is increasingly more problematic to analyze and understand, from a ISP point of view, what CO price list a given access should apply to. More and more CO divides their accesses into different price groups. Examples are SDU vs MDU, special aggreements with a larger Network Owners, the wish to offer lower prices company services in certain areas, citylans vs fiber association (stadsnät vs byalag) etc.

No field in the current accesses endpoint is dedicated to this. No field is for CO->ISP specifically.

The current approach has been to use other fields (by themselves or in combination) or even to analyze the available services in the services-sup-part. Neither of them solves the problem and are scalable.

The primary field today is "population". It is a CO field and was not intended to be used for logic. It is a freetext field so prone to spelling errors. When the number of different price lists increases, the ISP side needs to include more and more logic to effectively parse the texts.

The secondary field is "premisesType" and is currently mostly used when there is a need to handle price lists for SDU, MDU and Company. If the CO has different regions, special agreements etc then this field is not enough by itself and then needs to be combined with other fields ("population" or available services).

A third use is to make ISP check the available services sub-part of the access and to use freetext search to identify what available services there are and with that data apply a price list. Just like "population" this does not scale, is not really futureproof (se #47 for changes to this structure) and suffers from the same spelling problem as above. The ISP also has to store all that data.

An example:
A CO called "BestFiberCO" has only one product (for simplicity) and implements a price list structure as follows:
Default:

• SDU/Residentual building: 200 SEK
• MDU/Apartment: 100 SEK
  RegionNorth:
• All: 250 SEK
  BigStockholmApartmentCustomer:
• All: 150 SEK

A customer wants to order and gives AID 123456. From the data in that access object the ISP now must know what price list to use in order to calculate end price. It must match to 1 and only 1 price list.

If the CO insists the population field is used for their purposes and only stores landlord (for example) the matching is virtually impossible.

If the CO has accurately used premisesType then we can differentiate between SDU and MDU but that will still not help us as RegionNorth and BigStockholm has different prices.

Population is therefore needed. If population is empty then use premisesType to see if SDU or MDU and apply either 200 (SDU) or 100 (MDU). If population is RegionNorth apply 250 to all and if it is BigStockholm then use 150. The CO could obviously also tag population="SDU" and population="MDU" and then premisesType would not be needed.

However there is a CO today that refuses to use population for these purposes. A combination of premisesType and searching the services sub-part of the access object for available services names is their solution.

Proposed solution:
A special field that is exclusively dedicated to this problem needs to be addes to the access object. The field should NOT be text and must not be null or empty.

Proposed name: priceGroup (unsigned integer)

0 = Special value the defines it as default price list.
1+ = Used by CO to "name" their price lists. Must be set and included in the CO-ISP price list agreement.

Every access MUST be matched to 1 and only 1 priceGroup. Changes must be communicated to ISP well in advance.

In the example above:
0 = Default SDU
1 = Default MDU
10 = RegionNorth
100 = BigStockholm

If a group of SDUs join together and negotiates a special price they can just be changed to a new priceGroup 20 and CO communicates the change and times. They are still premisesType=ResidentialBuilding, their population is intact, no need for naming special services.

CO Change

A new process for CO Change has been released in "beta". See SSNF.

How can ON-api be a part in facilitating a more streamlined and effective CO Change process?
Does /accesses need more fields (datetime fields when an access is to be migrated in our out) or new statuses in accessState (UNDER_MIGRATION)?
Could changes be announced from a CO using new endpoints so as to remove Excel files and at the same time making sure the data is validated and correct?

A major problem is of course that there are two COs (or more) involved with a change. One is loosing accesses and one is gaining. Service Providers needs data from both in order to handle customer services in a correct fashion.

As soon as either part (old or new CO) knows any dates they need to prepare their access data. The old needs to change accessState = (UNDER_MIGRATION?) to indicate to ISPs that the accesses are under a change. The new CO needs to add the accesses with accessState = PLANNED and make them available to ISPs AND set OldAccessID to the old COs ID early to facilitate forward migration.

There should only be 1 financial date (when the economic changes happen, i.e. the old CO stops invoicing ISP and the new starts) for a single CO Change. So economic dates (enddate for old CO and startdate for new CO) needs to be added to both COs services or access entities. This is to make sure ISP and End customer gets correctly invoiced. It should be the start of a month.

There can be many technical migration dates when the actual migration occurs in a single CO Change. So technical dates needs to be added to both COs services or access entities. As these might change (which happens very often) they should only be for customer support purposes and as an indication om intent. When the actual migration has occurred, the old CO needs to set accessState = Disconnected and the new CO needs to set accessState = Connected.

There is of course a lot of additional data that needs to be preparred from the new CO (DHCP identifiers etc) but if a CO Change in combination with existing endpoints could be used then a lot could be handled via the normal operations.

There will probably be a need to for new endpoints. A general one where any changes are "advertised" and data can be retrieved.
There might alse be a need for secondary endpoints where ISP can control what services are affected, the data (spRef, spSubscriptionId etc) is to be moved from old to new, what new data (SubscriptionId, service) that is created in the new COs systems etc. The purpose is to make sure that correct services is transferred to the right accesses, that all internal controlling is OK, to minimize errors, to make sure invoicing and end user communications is correct and as effective as possible,

Option82 lookup history and accessId

When rebuilding the network, for example consolidating switches or moving an address to a new switch port or updating an address the option82 lookup will look for an now non-existing option82 value or point to a new address.

I would like to propose a change to the option82 lookup adding a validFrom field indicating from when the option82 value and accessId is valid and also show previous accessIds the option82 value has been connected to.

Or is this not considered a problem?

Standardized message when status is DONE_FAILED

I would like the messages when the Order API return status DONE_FAILED to be standardized, I.e. for example, when the port is blocked, then the message could be "port is blocked", then the SP can build logic to manage these errors in a better way.

Do you agree and do you have any suggestions on standardized messages?

message	description
Service is already claimed by other Service Provider	Another Service Provider have already purchased the service
accessId does not exist	The given accessId does not exist
Service cannot be activated before [DATE]	The order was placed before connection
Still processing previous order on this access	A previous order on this accessId is still processing

Product & campaign API

Suggestion on how a product & campaign API could look like:

{
  "coServiceId": "3456",
  "coService": "B2-100-100",
  "spService": "Internet 100/100 Mbps",
  "spServiceId": "2347",
  "commitment": "12",
  "noticePeriod": "1",
  "startFee": "295",
  "monthlyCost": "399",
  "startSales": "2020-12-03",
  "endSales": "2030-12-03",
  "campaign": [
    {
      "campId": "1234",
      "campDesciption": "299:- i 6 månader och fri start",
      "startSales": "2020-12-1",
      "endSales": "2030-12-1",
      "discounts": [
        {
          "discountId": "1234",
          "duration": "6",
          "discount": "-100"
        },
        {
          "discountId": "1235",
          "duration": "0",
          "discount": "-295"
        }
      ]
    },
    {
      "campId": "1236",
      "campDesciption": "Fri start",
      "startSales": "2020-12-1",
      "endSales": "2030-12-1",
      "discounts": [
        {
          "discountId": "1234",
          "recurring": "0",
          "duration": "0",
          "discount": "-295"
        }
      ]
    }
  ],
  "isPreactivatd": "false"
}

I hope it's self-explanatory, if not, please let me know.

Accesses: Dates for activation/inactivation

In the current specification for Access only accessState (enum) exists. This is not enough in an environment where accesses has a life cycle. As more and more accesses change CO there is a need for SP to understand when accesses is to be removed or being activated.

Two different sets of dates is needed:

Technical dates:

• StartDate when an access is planned to be active (accessState=PLANNED, DEPLOYING, HOMESPASSED) or is active (accessState=CONNECTED).
• EndDate when an access is planned to be inactive (accessState=MISSING ENUM FOR THIS) or is inactive (accessState=DISCONNECTED).

Commersial dates:

• StartDate when billing starts.
• EndDate when billing stops.

This is to handle two cases especially regarding CO changes.
The Old CO must mark the access universe to be removed from them and at the same time make sure SP does not get billed after the commercial break date regardless when the access is migrated technically.
The New CO must add the accesses as soon as possible to their universe (to give alla SPs a chance to forward migrate in their systems as early as possible) and make sure nothing is billed until the commercial break date.

This will also give SP more information when queriying an access for example in the process of a new customer activation. Dates in the EndDate fields should give Customer Service a reason to pause and know something is going on.

This will also help in controlling scenarios when controlling active services versus billing.

Extend technical info with more troubleshooting information

First and second line support staff, need information that is not possible to represent with the current specification of technical_info, I propose to add these capabilities to technical info.

Detail about what I have found to be missing, can be seen in this PR: #83

Structure for image files and other documents or binaries

With the suggestions of flowcharts a need of a folder structure is needed to host these files in the repository.
Should we just add folders like "2.4/images/" or should we prepare for a more advanced structure of future files
2.4/files/binaries/, 2.4/files/images/, 2.4/documents/

Include information about service agreement on property in Technical Info API?

Some network owners doesn't have service agreement on all their property owners, resulting in different lead time on support tickets for end customers. Some document this in their OSS/BSS system (NA, BBE etc.), but I think it could be interesting to look into if this information could be available in any appropriate API service in ONAPI. Maybe Technical Info and/or Tickets?

Suggestion for improved meter's address examples

In the Accesses API there is an example that I think is missing the last digit:
In the example of "Lantvägen 550-70", the street number is "550-7".

I assume that the last 0 is missing? In that case, I also suggest to add this example under streetLittera:
In the example of "Lantvägen 550-70", the street littera is empty.

Complete example texts:
streetNumber
In the example of "Kungsgatan 10G", the street number is "10". In the example of "Lantvägen 550-70", the street number is "550-70".

streetLittera
Street littera or entrance. In the example of "Kungsgatan 10G", the street littera is "G". In the example of "Lantvägen 550-70", the street littera is empty.

Two way order management

Be able to send from CO to SP. (Copied from old google sheets list)

Addon below by Teemu Frösén on October 20th 2020

The two way order communication will support all existing business models. ON-API 2.4 supports orders created from SP channels, see orders.md. ON-API 2.5 introduces a new endpoint called co_orders.md which enables automation of orders created from CO channels.

Existing business models for orders

• Order created from SP channels
• Order created from CO channels
  • Technical service preactivated by CO
  • Technical service not preactivated by CO

Suggested parameters for new endpoint

• Order
  • coOrderId
  • orderDate
  • deliveryDate
• Customer
  • ssn
  • customerFirstname
  • customerLastName
  • customerPhone
  • customerMobilePhone
  • customerEmail
• Access
  • accessId
  • streetName
  • streetNumber
  • streetLittera
  • entrance
  • apartmentNumber
  • city
  • zipcode
• Service
  • service
  • commitment
  • noticePeriod
  • campaign
  • isPreactivated

Order processes / business models to support

Order created from SP channels - service activated by SP

Order created from CO channels - service preactivated by CO

Order created from CO channels - service not preactivated by CO

Adding support for ASCII on opt82

Opt82 only supports hexadecimal according to 2.3.1 specs. Any thoughts on adding ASCII?

Add lastUpdate to accesses API

Accesses API does not describe when the address was changed, compared to Ekelundhs marketdatabase which includes lastUpdate. In the case of marketdatabase, it does not say what data on the address that have been updated, but it could be used to only fetch changed addresses to reduce server load and speed up address related operations. For example /accesses/lastupdate/2021-06-01.

Thoughts and input?

Order notice without implementing the Products endpoint

Hi!

I'm currently developing the ON-API v2.4+ versions for iTUX.
When an end customer orders a service we currently notify service providers of this mainly by email, but there's also some support for pushing such orders to a service provider using a really old SOAP api specification.

I noticed the new Order Notice v2.5 part of the spec and thought that it would be a good replacement over the old SOAP integrations. But it seems to me that it would be necessary for a service provider to implement both the order notice endpoint and the Products endpoint as the product information is required in the order notice api.

I understand that this is nice for the service providers that want to handle all offers and products in one place (their own systems) and I hope that one day all service providers will do this, because I for one would love to get rid of all complicated offer and campaign UI's we have to build/maintain. For many of our service providers we are working with this will probably never be the case though, so we are stuck with continuing supporting the service provider to administer their campaigns/offers in our UI.
But many of those service providers would still like to be notified of new orders in other ways than via email, and we as developers want to get rid of SOAP completely.

So my suggestion is that the Order Notice api is slightly modified so that the products.productId and products.offeringId are made optional. Maybe with a condition such that they are required if the service provider has implemented the products endpoint, but optional otherwise.

What do you think about my reasoning?