User Guide FIT Product Ordering Management API

AG-FIT 622

Release 1.0.0 (Build 191) 2024-12-19 released

The following document is the user guide of the REST API for Product Ordering management. It includes the model definition as well as all available operations. The Product Ordering API provides a standardized mechanism for placing a product order with all of the necessary order parameters. The API consists of a simple set of operations that interact with Customer Relationship Management / Order Negotiation systems in a consistent manner. A product order is created based on a product offer that is defined in a catalog. The product order references the product offer and identifies any specific requests made by the customer. Product Ordering API manages product order resource:

• A Product Order is a type of order which can be used to place an order between a customer and a service provider or between a service provider and a partner and vice versa
• Main Product Order attributes are its identifier, state (acknowledged, inProgress, completed...), priority, category, related dates, related billing account, related parties and order items
• Main Order Items (aka order lines) attributes are the ordered offering and product characteristics with the related action to be performed (e.g. add or delete the products), state, location information for delivery. Product ordering API performs the following operations on Product Order:
• Creation of a product order (including default values and creation rules)
• Retrieval of a product order or a collection of product orders depending on filter criteria
• Notification of events on product order
  • Product Order creation
  • Product Order state change
  • Product Order atribute value change used to notify that any data in an order has just changed
  • Product Order information required used to notify that some data in the order need to be filled / are missing
  • Product Order jeopardy alert
  • Product Order milestone

Product ordering API performs the following operations on CancelProductOrder:

• Creation of a product order cancel request
• Retrieval of a product order cancellation request or a collection of product order cancellation requests depending on filter criteria
• Notification of events on product order cancel
  • Cancel Product Order state change

Product ordering API performs the following operations on CloseProductOrder (FIT only, for closing an existing product order):

• Creation of a product order close request
• Retrieval of a product order close request or a collection of product order close requests depending on filter criteria
• Notification of events on product order close
  • Close Product Order state change

Product ordering API performs the following operations on RespondProviderChange (FIT only, to provide a response to an existing provider change product order):

• Creation of a respond provider change request
• Retrieval of a respond provider change request or a collection of respond provider change requests depending on filter criteria
• Notification of events on respond provider change
  • Respond provider change state change

Product ordering API performs the following operations on RescheduleProductOrder (FIT only, for rescheduling an existing product order):

• Creation of a reschedule product order request
• Retrieval of a reschedule product order request or a collection of reschedule product order requests depending on filter criteria
• Notification of events on reschedule product order
  • Reschedule product order state change

Product ordering API performs the following operations on AddProductOrderInformation (FIT only, for rescheduling an existing product order):

• Creation of an add product order information request
• Retrieval of an add product order information request or a collection of add product order information requests depending on filter criteria
• Notification of events on of add product order information
  • Add product order information request state change

Product ordering API performs the following operations on AmendProductOrder (FIT only, for rescheduling an existing product order):

• Creation of an amend product order request
• Retrieval of an amend product order request or a collection of amend product order requests depending on filter criteria
• Notification of events on of amend product order
  • Amend product order request state change

FIT Adapations

ProductOrder resource:

• PATCH & DELETE are not used for FIT
• added state change history (based on TMF621)
• Milestone / JeopardyAlert adapted to FIT requirements
• added ProviderChangeInfo to document provider change agreement
• added requestedTimeSlot to provide time slot request for appointment
• added alternateProductOffering

CloseProductOrder task resource: added task resource for closing an existing product order

RespondProviderChange task resource: added task resource to provide a response to an existing provider change product order

RescheduleProductOrder task resource: added task resource for rescheduling an existing product order

AddProductOrderInformation task resource: added task resource to add information to an existing product order

AmendProductOrder task resource: added task resource to amend an existing product order

Sources

The source API definition can be found at fit-tmf622.yaml

Documentation for API Endpoints

All URIs are relative to https://api.example.com/tmf-api/productOrderingManagement/v5

Method	HTTP request	Description
createProductOrder	POST /productOrder	Creates a ProductOrder
listProductOrder	GET /productOrder	List or find ProductOrder objects
retrieveProductOrder	GET /productOrder/{id}	Retrieves a ProductOrder by ID
createCancelProductOrder	POST /cancelProductOrder	Creates a CancelProductOrder
listCancelProductOrder	GET /cancelProductOrder	List or find CancelProductOrder objects
retrieveCancelProductOrder	GET /cancelProductOrder/{id}	Retrieves a CancelProductOrder by ID
createRescheduleProductOrder	POST /rescheduleProductOrder	Creates a RescheduleProductOrder
listRescheduleProductOrder	GET /rescheduleProductOrder	List or find RescheduleProductOrder objects
retrieveRescheduleProductOrder	GET /rescheduleProductOrder/{id}	Retrieves a RescheduleProductOrder by ID
createRespondProviderChange	POST /respondProviderChange	Creates a RespondProviderChange
listRespondProviderChange	GET /respondProviderChange	List or find RespondProviderChange objects
retrieveRespondProviderChange	GET /respondProviderChange/{id}	Retrieves a RespondProviderChange by ID
createCloseProductOrder	POST /closeProductOrder	Creates a CloseProductOrder
listCloseProductOrder	GET /closeProductOrder	List or find CloseProductOrder objects
retrieveCloseProductOrder	GET /closeProductOrder/{id}	Retrieves a CloseProductOrder by ID
createAddProductOrderInformation	POST /addProductOrderInformation	Creates an AddProductOrderInformation
listAddProductOrderInformation	GET /addProductOrderInformation	List or find AddProductOrderInformation objects
retrieveAddProductOrderInformation	GET /addProductOrderInformation/{id}	Retrieves a AddProductOrderInformation by ID
createAmendProductOrder	POST /amendProductOrder	Creates an AmendProductOrder
listAmendProductOrder	GET /amendProductOrder	List or find AmendProductOrder objects
retrieveAmendProductOrder	GET /amendProductOrder/{id}	Retrieves a AmendProductOrder by ID
createHub	POST /hub	Create a subscription (hub) to receive Events
hubDelete	DELETE /hub/{id}	Remove a subscription (hub) to receive Events
listenToProductOrderCreateEvent	POST /listener/productOrderCreateEvent	Client listener for ProductOrderCreateEvent
listenToProductOrderStateChangeEvent	POST /listener/productOrderStateChangeEvent	Client listener for ProductOrderStateChangeEvent
listenToProductOrderAttributeValueChangeEvent	POST /listener/productOrderAttributeValueChangeEvent	Client listener for ProductOrderAttributeValueChangeEvent
listenToProductOrderInformationRequiredEvent	POST /listener/productOrderInformationRequiredEvent	Client listener for ProductOrderInformationRequiredEvent
listenToProductOrderJeopardyAlertEvent	POST /listener/productOrderJeopardyAlertEvent	Client listener for ProductOrderJeopardyAlertEvent
listenToProductOrderMilestoneEvent	POST /listener/productOrderMilestoneEvent	Client listener for ProductOrderMilestoneEvent
listenToCancelProductOrderStateChangeEvent	POST /listener/cancelProductOrderStateChangeEvent	Client listener for CancelProductOrderStateChangeEvent
listenToRescheduleProductOrderStateChangeEvent	POST /listener/rescheduleProductOrderStateChangeEvent	Client listener for RescheduleProductOrderStateChangeEvent
listenToRespondProviderChangeStateChangeEvent	POST /listener/respondProviderChangeStateChangeEvent	Client listener for RespondProviderChangeStateChangeEvent
listenToCloseProductOrderStateChangeEvent	POST /listener/closeProductOrderStateChangeEvent	Client listener for CloseProductOrderStateChangeEvent
listenToAddProductOrderInformationStateChangeEvent	POST /listener/addProductOrderInformationStateChangeEvent	Client listener for AddProductOrderInformationStateChangeEvent
listenToAmendProductOrderStateChangeEvent	POST /listener/amendProductOrderStateChangeEvent	Client listener for AmendProductOrderStateChangeEvent

Documentation for Authorization

OAuth2ClientCredentials

• Type: OAuth

• Flow: clientCredentials

• Token URL: https://auth.example.org/oauth2/token/

• Scopes:
  • read: read objects
  • write: write objects

This API can be secured using OAuth 2.0. OAuth separates the authentication provider from the resource. The authorization server issues access tokens which are used to access the protected resource. This allows consumption of the API without sharing credentials with the API provider. OAuth 2.0 is implemented in various ways using flows. The most common flow for machine-to-machine interfaces is the Client Credentials flow. This is the flow used for this API. Below is a sequence diagram illustrating the Client Credentials flow.

See also Api Authentifizierung

Sample use cases

Sample use cases can be found at Auftrag (Neu) anlegen

Managed Entity Resource Models

Product Order

A Product Order is a type of order which can be used to place an order between a customer and a service provider or between a service provider and a partner and vice versa.

Lifecycle

ProductOrderStateType

Data type: enum of string

Possible values for the state of the order:

• acknowledged: The Acknowledged state is where an order/item has been received and has passed message level validation (e. g. schema, conformance profile). The order is stored and addressable.
• accepted: The Accepted state is where an order has passed business validation. Several operations, e. g. storno, are possible.
• rejected: The Rejected state is where:
  - An order failed the Order Feasibility check
  - Invalid information is provided through the order request
  - The order request fails to meet business rules for ordering
  Same rules applied for order item.
• pending: The Pending state is used when an order/item is currently in a waiting stage for an action/activity to be completed before the order/item can progress further, pending order amend or cancel assessment. In situations where Access Seeker action is required, an “information required” notification will be issued on transition into this state. A pending stage can lead into auto cancellation of an order/item, if no action is taken within the defined timeframes to be described under the Agreement.
• inProgress: The In Progress state is where an order Item has passed the Order Feasibility check successfully and product delivery has started. For the order at least one order item is inProgress.
• held: The Held state is used when an order/item cannot be progressed due to an issue. SP has temporarily delayed completing an order/item to resolve an infrastructure shortfall to facilitate supply of order. Upon resolution of the issue, the order/item will continue to progress.
• assessingCancellation: Following a cancel request, the SP is assessing if cancel can be done for the order/item (or if the PO has reached PONR). If cancellation request is not accepted after assessment the order will return to Held or Pending or InProgress state.
• cancelled: The Cancelled state is where an In-Flight Order/item has been successfully cancelled.
• completed: The Completed state is where an item has complete provision and the service is now active. For an order all order items are completed.
• closed: The post-provisioning activities such as billing account update have been finalized. The order is Closed.
• failed: Order item as not a successful delivery completion. The product is not delivered and the order item failed. All Order items have failed which results in the entire Order has Failed.

Resource model

Field description

Complex types used can be viewed by following the linked type.

ProductOrder

Data type: Entity

A Product Order is a type of order which can be used to place an order between a customer and a service provider or between a service provider and a partner and vice versa,

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
category (1)	string	Used to categorize the order from a business perspective (new, productChange, groupChange, productModification, termination, groupMigration)	new
creationDate (1)	DateTime	Date when the order resource was created	2023-01-01T08:00+01:00
productOrderItem (1)	ProductOrderItem [1..m]	Product order item	[]
state (1)	ProductOrderStateType
stateChangeDate (1)	DateTime	The date and time the state changed.	2024-01-01T12:00+01:00
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
id	string	Unique identifier	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
href	URI	Hyperlink reference	https://api.example.org/resource/id
description	string	Description of the product order	Lorem ipsum dolor
expectedCompletionDate	DateTime	Expected delivery date amended by the provider	2025-12-24T19:30+01:00
orderIsChargingRelevant	boolean	Boolean amended by the provider defining if the processing of the ProductOrder is charging relevant	false
orderPostedDate	DateTime	Date when the order was posted by the requester	2023-01-01T08:00+01:00
priority	string	A way that can be used by consumers to prioritize orders in OM system (from 0 to 4 : 0 is the highest priority, and 4 the lowest)	4
requestedCompletionDate	DateTime	Requested delivery date from the requestors perspective	2025-12-24T19:30+01:00
agreement	AgreementRefOrValue [n..m]	A reference to an agreement defined in the context of the product order	[]
externalId	ExternalIdentifier [n..m]	A reference to an externaly defined object in the context of the product order	[]
billingAccount	BillingAccountRef
note	Note [n..m]	Note	[]
productOfferingQualification	ProductOfferingQualificationRef [n..m]	Product offering qualification	[]
relatedParty	RelatedPartyOrPartyRole [n..m]	Related party	[]
stateChangeReason	Message [n..m]	Reason for the state change described as a combination of a text and a code.	[]
stateChangeHistory	StateChange [n..m]	The state change history that is associated to the Entity. Populated by the server	[]
earliestOrderRetry	DateTime	Earliest date when the order can be submitted again.	2023-01-01T08:00+01:00
attachment	AttachmentRefOrValue [n..m]	Attachment	[]
productOrderJeopardyAlert	ProductOrderJeopardyAlert [n..m]	List of ProductOrderJeopardyAlerts. A ProductOrderJeopardyAlert represents a predicted exception during a product order processing that would brings risk to complete successfully the order.	[]
productOrderMilestone	ProductOrderMilestone [n..m]	List of ProductOrderMilestones. A ProductOrderMilestone represents an action or event marking a significant change or stage in processing of a product order.	[]
productOrderRelationship	ProductOrderRelationship [n..m]	Product order relationship	[]
providerChangeInfo	ProviderChangeInfo
additionalOrderInformation	AdditionalOrderInformation

JSON representation sample

We provide below the JSON representation of an example of a 'ProductOrder' resource object

{
  "@type" : "ProductOrder",
  "id" : "388a4963-f168-4603-99e8-477200099d91",
  "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/productOrder/388a4963-f168-4603-99e8-477200099d91",
  "category" : "new",
  "creationDate" : "2022-05-11T10:30:30+02:00",
  "orderPostedDate" : "2022-05-11T10:30:00+02:00",
  "requestedCompletionDate" : "2022-12-01T12:00:00+01:00",
  "agreement" : [ {
    "@type" : "Agreement",
    "name" : "buyerServiceContract",
    "engagedParty" : [ {
      "@type" : "Organization",
      "businessId" : "500011"
    } ],
    "businessId" : "500012",
    "agreementType" : "buyerServiceContract"
  }, {
    "@type" : "Agreement",
    "name" : "ordererServiceContract",
    "engagedParty" : [ {
      "@type" : "Organization",
      "businessId" : "500014"
    } ],
    "businessId" : "500013",
    "agreementType" : "ordererServiceContract"
  }, {
    "@type" : "Agreement",
    "name" : "providerChangeAgreement",
    "businessId" : "DEU.VFD.V012345678",
    "agreementType" : "providerChangeAgreement"
  } ],
  "externalId" : [ {
    "@type" : "ExternalIdentifier",
    "id" : "1000111",
    "externalIdentifierType" : "ProductOrder",
    "owner" : "DEU.VFD"
  } ],
  "productOrderItem" : [ {
    "@type" : "ProductOrderItem",
    "id" : "1",
    "action" : "add",
    "product" : {
      "@type" : "BitstreamAccessProduct",
      "creationDate" : "2022-05-11T10:30:30+02:00",
      "relatedPlace" : [ {
        "@type" : "RelatedPlaceRefOrValue",
        "role" : "locationA",
        "place" : {
          "@type" : "GeographicAddress",
          "city" : "Rheinhausen",
          "country" : "DE",
          "locality" : "Nordstadt",
          "postcode" : "59055",
          "streetName" : "Biberweg",
          "streetNr" : "2",
          "streetNrSuffix" : "a",
          "geographicSubAddress" : [ {
            "@type" : "GeographicSubAddress",
            "buildingName" : "Einfamilienhaus"
          } ]
        }
      } ],
      "networkTerminationUnitLocation" : "Flur 3.OG",
      "homeId" : "a12d5a4545"
    },
    "productOffering" : {
      "@type" : "ProductOffering",
      "name" : "FTTH 250000"
    },
    "requestedTimeSlot" : {
      "@type" : "TimeSlot",
      "validFor" : {
        "startDateTime" : "2022-12-01T08:00:00+01:00",
        "endDateTime" : "2022-12-01T12:00:00+01:00"
      }
    }
  } ],
  "relatedParty" : [ {
    "@type" : "RelatedPartyOrPartyRole",
    "role" : "orderManagementBuyerContact",
    "partyOrPartyRole" : {
      "@type" : "Individual",
      "contactMedium" : [ {
        "@type" : "PhoneContactMedium",
        "contactType" : "fixed",
        "phoneNumber" : "+49221456789"
      }, {
        "@type" : "PhoneContactMedium",
        "contactType" : "mobile",
        "phoneNumber" : "+4917754545454"
      }, {
        "@type" : "EmailContactMedium",
        "contactType" : "email",
        "emailAddress" : "j.kirk@example.net"
      } ],
      "familyName" : "Kirk",
      "salutation" : "Herr",
      "givenName" : "James T.",
      "title" : "Captain"
    }
  }, {
    "@type" : "RelatedPartyOrPartyRole",
    "role" : "installationContact",
    "partyOrPartyRole" : {
      "@type" : "Individual",
      "contactMedium" : [ {
        "@type" : "PhoneContactMedium",
        "contactType" : "fixed",
        "phoneNumber" : "+49221145155"
      }, {
        "@type" : "PhoneContactMedium",
        "contactType" : "mobile",
        "phoneNumber" : "+4917878878788"
      }, {
        "@type" : "EmailContactMedium",
        "contactType" : "email",
        "emailAddress" : "a.fischer@example.net"
      } ],
      "familyName" : "Fischer",
      "salutation" : "Herr",
      "givenName" : "Alexander"
    }
  }, {
    "@type" : "RelatedPartyOrPartyRole",
    "role" : "locationAContact",
    "partyOrPartyRole" : {
      "@type" : "Individual",
      "contactMedium" : [ {
        "@type" : "PhoneContactMedium",
        "contactType" : "fixed",
        "phoneNumber" : "+49221145155"
      }, {
        "@type" : "PhoneContactMedium",
        "contactType" : "mobile",
        "phoneNumber" : "+4917878878788"
      } ],
      "familyName" : "Fischer",
      "salutation" : "Herr",
      "givenName" : "Alexander"
    }
  } ],
  "state" : "acknowledged",
  "stateChangeDate" : "2022-05-11T10:30:00+02:00",
  "additionalOrderInformation" : {
    "campaignIdentifier" : "PromotionFiber",
    "projectIdentifier" : "AB1234",
    "couplingIdentifier" : "QW567",
    "orderBindingId" : "AK45678",
    "orderBindingNumberOfOrders" : 5,
    "hardwareIdType" : "OntSerialNumber",
    "hardwareIdValue" : "1234567890"
  }
}

To view more examples go to TMF622 examples

Task Resource Models

Lifecycle

TaskStateType

Data type: enum of string

Possible values for the state of a task are:

• acknowledged: The acknowledged state is used if a task resource has been received and has passed message and basic business validations.
• rejected: The task has been rejected during validation or processing.
• inProgress: The InProgress state is used while the task is being processed.
• done: The task has been completed and a result is available.
• terminatedWithError: The task could not be correctly completed and no result is available.

Cancel Product Order task resource

Resource model

Field description

CancelProductOrder

Data type: TaskEntity

Request for cancellation an existing product order

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
productOrder (1)	ProductOrderRef
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
id	string	Unique identifier	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
href	URI	Hyperlink reference	https://api.example.org/resource/id
state	TaskStateType
stateChangeDate	DateTime	The date and time the state changed.	2023-01-01T08:00+01:00
stateChangeReason	Message [n..m]	Reason for the state change described as a combination of a text and a code.	[]
requestDate	DateTime	Date when the task resource was created	2023-01-01T08:00+01:00
requestPostedDate	DateTime	Date when the request was posted	2023-01-01T08:00+01:00
stateChangeHistory	StateChange [n..m]	The state change history that is associated to the Entity. Populated by the server	[]
externalIdentifier	ExternalIdentifier [n..m]	A reference to an externally defined object in the context of the managed entity	[]
cancellationReason	Message [n..m]	Reason for cancellation request described as a combination of a text and a code.	[]

JSON representation sample

{
  "@type" : "CancelProductOrder",
  "id" : "2fd01b2b-9110-41ed-8efd-014d7e8ee158",
  "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/cancelProductOrder/2fd01b2b-9110-41ed-8efd-014d7e8ee158",
  "state" : "acknowledged",
  "stateChangeDate" : "2022-05-11T11:25:00+02:00",
  "stateChangeReason" : [ {
    "code" : "code",
    "text" : "acknowledged_Reason"
  } ],
  "requestPostedDate" : "2022-05-11T11:25:00+02:00",
  "productOrder" : {
    "@type" : "ProductOrderRef",
    "id" : "388a4963-f168-4603-99e8-477200099d91",
    "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/productOrder/388a4963-f168-4603-99e8-477200099d91"
  },
  "cancellationReason" : [ {
    "code" : "001",
    "text" : "I don't want this anymore."
  } ]
}

Reschedule Product Order task resource

Resource model

Field description

RescheduleProductOrder

Data type: TaskEntity

Request to reschedule an existing product order

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
productOrder (1)	ProductOrderRef
rescheduledRequestedCompletionDate (1)	DateTime	Rescheduled requested delivery date from the requester perspective	2025-12-24T19:30+01:00
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
id	string	Unique identifier	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
href	URI	Hyperlink reference	https://api.example.org/resource/id
state	TaskStateType
stateChangeDate	DateTime	The date and time the state changed.	2023-01-01T08:00+01:00
stateChangeReason	Message [n..m]	Reason for the state change described as a combination of a text and a code.	[]
requestDate	DateTime	Date when the task resource was created	2023-01-01T08:00+01:00
requestPostedDate	DateTime	Date when the request was posted	2023-01-01T08:00+01:00
stateChangeHistory	StateChange [n..m]	The state change history that is associated to the Entity. Populated by the server	[]
externalIdentifier	ExternalIdentifier [n..m]	A reference to an externally defined object in the context of the managed entity	[]
rescheduleReason	Message [n..m]	Reason for rescheduling request	[]
productOrderItem	ProductOrderItemId

JSON representation sample

{
  "@type" : "RescheduleProductOrder",
  "id" : "33359a1e-134f-4b0f-98a8-acc91af5bbee",
  "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/rescheduleProductOrder/33359a1e-134f-4b0f-98a8-acc91af5bbee",
  "state" : "acknowledged",
  "stateChangeDate" : "2022-07-20T09:00:00+02:00",
  "stateChangeReason" : [ {
    "code" : "code",
    "text" : "acknowledged_Reason"
  } ],
  "productOrder" : {
    "@type" : "ProductOrderRef",
    "id" : "388a4963-f168-4603-99e8-477200099d91",
    "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/productOrder/388a4963-f168-4603-99e8-477200099d91"
  },
  "rescheduledRequestedCompletionDate" : "2022-07-20T12:00:00+02:00",
  "rescheduleReason" : [ {
    "code" : "002",
    "text" : "I'm on vacation."
  } ],
  "productOrderItem" : {
    "id" : "1",
    "requestedTimeSlot" : {
      "@type" : "TimeSlot",
      "validFor" : {
        "startDateTime" : "2022-07-20T08:00:00+02:00",
        "endDateTime" : "2022-07-20T12:00:00+02:00"
      }
    }
  }
}

Respond Provider Change task resource

Resource model

Field description

RespondProviderChange

Data type: TaskEntity

Response to an existing provider change product order

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
productOrder (1)	ProductOrderRef
approval (1)	boolean	Whether the approval has been given	true
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
id	string	Unique identifier	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
href	URI	Hyperlink reference	https://api.example.org/resource/id
state	TaskStateType
stateChangeDate	DateTime	The date and time the state changed.	2023-01-01T08:00+01:00
stateChangeReason	Message [n..m]	Reason for the state change described as a combination of a text and a code.	[]
requestDate	DateTime	Date when the task resource was created	2023-01-01T08:00+01:00
requestPostedDate	DateTime	Date when the request was posted	2023-01-01T08:00+01:00
stateChangeHistory	StateChange [n..m]	The state change history that is associated to the Entity. Populated by the server	[]
externalIdentifier	ExternalIdentifier [n..m]	A reference to an externally defined object in the context of the managed entity	[]
responseReason	Message [n..m]	Reason for response	[]

JSON representation sample

{
  "@type" : "RespondProviderChangeStateChangeEvent",
  "eventId" : "e25523f1-a75d-4e72-b05a-3d0d7dca5862",
  "eventTime" : "2022-05-11T10:36:00+02:00",
  "eventType" : "RespondProviderChangeStateChangeEvent",
  "event" : {
    "respondProviderChange" : {
      "@type" : "RespondProviderChange",
      "id" : "892cfa45-fca3-488d-8a7c-2883923f820e",
      "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/respondProviderChange/892cfa45-fca3-488d-8a7c-2883923f820e",
      "state" : "inProgress",
      "stateChangeDate" : "2022-05-11T10:36:00+02:00",
      "stateChangeReason" : [ {
        "code" : "code",
        "text" : "inProgress_Reason"
      } ],
      "requestPostedDate" : "2022-05-11T10:35:00+02:00",
      "stateChangeHistory" : [ {
        "@type" : "StateChange",
        "stateChangeDate" : "2022-05-11T10:35:00+02:00",
        "state" : "acknowledged"
      } ],
      "productOrder" : {
        "@type" : "ProductOrderRef",
        "id" : "596d7fa0-981f-4b98-bcf5-e9b2955776f4",
        "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/productOrder/596d7fa0-981f-4b98-bcf5-e9b2955776f4"
      },
      "approval" : true
    }
  }
}

Close Product Order task resource

Resource model

Field description

CloseProductOrder

Data type: TaskEntity

Request for closing an existing product order

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
productOrder (1)	ProductOrderRef
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
id	string	Unique identifier	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
href	URI	Hyperlink reference	https://api.example.org/resource/id
state	TaskStateType
stateChangeDate	DateTime	The date and time the state changed.	2023-01-01T08:00+01:00
stateChangeReason	Message [n..m]	Reason for the state change described as a combination of a text and a code.	[]
requestDate	DateTime	Date when the task resource was created	2023-01-01T08:00+01:00
requestPostedDate	DateTime	Date when the request was posted	2023-01-01T08:00+01:00
stateChangeHistory	StateChange [n..m]	The state change history that is associated to the Entity. Populated by the server	[]
externalIdentifier	ExternalIdentifier [n..m]	A reference to an externally defined object in the context of the managed entity	[]
closeReason	Message [n..m]	Reason for closing request described as a combination of a text and a code.	[]

JSON representation sample

{
  "@type" : "CloseProductOrder",
  "id" : "a32b3fee-e1f0-4b3b-9fee-3907a8bdaac1",
  "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/closeProductOrder/a32b3fee-e1f0-4b3b-9fee-3907a8bdaac1",
  "state" : "acknowledged",
  "stateChangeDate" : "2022-06-03T10:41:00+02:00",
  "stateChangeReason" : [ {
    "code" : "code",
    "text" : "acknowledged_Reason"
  } ],
  "requestPostedDate" : "2022-06-03T10:41:00+02:00",
  "productOrder" : {
    "@type" : "ProductOrderRef",
    "id" : "388a4963-f168-4603-99e8-477200099d91",
    "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/productOrder/388a4963-f168-4603-99e8-477200099d91"
  },
  "closeReason" : [ {
    "code" : "111",
    "text" : "TBD"
  } ]
}

Add Product Order Information task resource

Resource model

Field description

AddProductOrderInformation

Data type: TaskEntity

Request for adding additional product order information an existing product order

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
productOrder (1)	ProductOrderRef
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
id	string	Unique identifier	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
href	URI	Hyperlink reference	https://api.example.org/resource/id
state	TaskStateType
stateChangeDate	DateTime	The date and time the state changed.	2023-01-01T08:00+01:00
stateChangeReason	Message [n..m]	Reason for the state change described as a combination of a text and a code.	[]
requestDate	DateTime	Date when the task resource was created	2023-01-01T08:00+01:00
requestPostedDate	DateTime	Date when the request was posted	2023-01-01T08:00+01:00
stateChangeHistory	StateChange [n..m]	The state change history that is associated to the Entity. Populated by the server	[]
externalIdentifier	ExternalIdentifier [n..m]	A reference to an externally defined object in the context of the managed entity	[]
relatedParty	RelatedPartyOrPartyRole
note	Note

JSON representation sample

{
  "@type" : "AddProductOrderInformation",
  "id" : "d1317bb6-969a-4da7-be54-2d3760e48fee",
  "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/addProductOrderInformation/d1317bb6-969a-4da7-be54-2d3760e48fee",
  "state" : "acknowledged",
  "stateChangeDate" : "2022-07-20T09:00:00+02:00",
  "stateChangeReason" : [ {
    "code" : "code",
    "text" : "acknowledged_Reason"
  } ],
  "productOrder" : {
    "@type" : "ProductOrderRef",
    "id" : "388a4963-f168-4603-99e8-477200099d91",
    "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/productOrder/388a4963-f168-4603-99e8-477200099d91"
  },
  "relatedParty" : {
    "@type" : "RelatedPartyOrPartyRole",
    "role" : "installationContact",
    "partyOrPartyRole" : {
      "@type" : "Individual",
      "contactMedium" : [ {
        "@type" : "PhoneContactMedium",
        "contactType" : "fixed",
        "phoneNumber" : "+49221145155"
      }, {
        "@type" : "PhoneContactMedium",
        "contactType" : "mobile",
        "phoneNumber" : "+4917878878788"
      }, {
        "@type" : "EmailContactMedium",
        "contactType" : "email",
        "emailAddress" : "a.fischer@example.net"
      } ],
      "familyName" : "Fischer",
      "salutation" : "Herr",
      "givenName" : "Alexander"
    }
  },
  "note" : {
    "@type" : "Note",
    "text" : "zweimal klingeln"
  }
}

Amend Product Order task resource

Resource model

Field description

AmendProductOrder

Data type: TaskEntity

Request for amending an existing product order

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
productOrder (1)	ProductOrderRef
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
id	string	Unique identifier	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
href	URI	Hyperlink reference	https://api.example.org/resource/id
state	TaskStateType
stateChangeDate	DateTime	The date and time the state changed.	2023-01-01T08:00+01:00
stateChangeReason	Message [n..m]	Reason for the state change described as a combination of a text and a code.	[]
requestDate	DateTime	Date when the task resource was created	2023-01-01T08:00+01:00
requestPostedDate	DateTime	Date when the request was posted	2023-01-01T08:00+01:00
stateChangeHistory	StateChange [n..m]	The state change history that is associated to the Entity. Populated by the server	[]
externalIdentifier	ExternalIdentifier [n..m]	A reference to an externally defined object in the context of the managed entity	[]
amendReason	Message [n..m]	Reason for the amend request (Message)	null
amendProductOrderItem	AmendProductOrderItem [n..m]	ProductOrderItem to be amended (id alone for delete, full ProductOrderItem for add and replace)	null

JSON representation sample

{
  "@type" : "AmendProductOrder",
  "id" : "f8d80f8c-7f70-4dca-aa25-a3321d50685d",
  "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/amendProductOrder/f8d80f8c-7f70-4dca-aa25-a3321d50685d",
  "state" : "acknowledged",
  "stateChangeDate" : "2022-07-20T09:00:00+02:00",
  "stateChangeReason" : [ {
    "code" : "code",
    "text" : "acknowledged_Reason"
  } ],
  "productOrder" : {
    "@type" : "ProductOrderRef",
    "id" : "388a4963-f168-4603-99e8-477200099d91",
    "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/productOrder/388a4963-f168-4603-99e8-477200099d91"
  },
  "amendProductOrderItem" : [ {
    "action" : "add",
    "productOrderItem" : {
      "@type" : "ProductOrderItem",
      "id" : "2",
      "action" : "add",
      "productOffering" : {
        "@type" : "ProductOffering",
        "name" : "Bereitstellung Komfort"
      },
      "productOrderItemRelationship" : [ {
        "@type" : "OrderItemRelationship",
        "id" : "1",
        "relationshipType" : "dependsOn"
      } ]
    }
  } ]
}

Notification Resource Models

Following notifications are defined for this API:

Notifications related to ProductOrder:

• ProductOrderCreateEvent
• ProductOrderStateChangeEvent
• ProductOrderAttributeValueChangeEvent
• ProductOrderInformationRequiredEvent
• ProductOrderJeopardyAlertEvent
• ProductOrderMilestoneEvent

Notifications related to CancelProductOrder:

• CancelProductOrderStateChangeEvent

Notifications related to CloseProductOrder:

• CloseProductOrderStateChangeEvent

Notifications related to RespondProviderChange:

• RespondProviderChangeStateChangeEvent

Notifications related to RescheduleProductOrder:

• RescheduleProductOrderStateChangeEvent

Notifications related to AddProductOrderInformation:

• AddProductOrderInformationStateChangeEvent

Notifications related to AmendProductOrder:

• AmendProductOrderStateChangeEvent

Product Order Create Event

ProductOrderCreateEvent

Data type: Event

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
eventId (1)	string	The identifier of the notification.	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
eventTime (1)	DateTime	Time of the event occurrence.	2023-01-01T08:00+01:00
eventType (1)	string	The type of the notification.
event (1)	ProductOrderCreateEventPayload
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
description	string	An explanatory of the event.	Lorem ipsum dolor
timeOccurred	DateTime	The time the event occurred.	2023-01-01T08:00+01:00
source	EntityRef
reportingSystem	EntityRef

JSON representation sample

Acknowledged JSON example

Product Order State Change Event

ProductOrderStateChangeEvent

Data type: Event

The notification data structure

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
eventId (1)	string	The identifier of the notification.	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
eventTime (1)	DateTime	Time of the event occurrence.	2023-01-01T08:00+01:00
eventType (1)	string	The type of the notification.
event (1)	ProductOrderStateChangeEventPayload
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
description	string	An explanatory of the event.	Lorem ipsum dolor
timeOccurred	DateTime	The time the event occurred.	2023-01-01T08:00+01:00
source	EntityRef
reportingSystem	EntityRef

JSON representation sample

Cancelled JSON example

Product Order Attribute Value Change Event

ProductOrderAttributeValueChangeEvent

Data type: AttributeValueChangeEvent

The notification data structure

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
eventId (1)	string	The identifier of the notification.	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
eventTime (1)	DateTime	Time of the event occurrence.	2023-01-01T08:00+01:00
eventType (1)	string	The type of the notification.
event (1)	ProductOrderAttributeValueChangeEventPayload
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
description	string	An explanatory of the event.	Lorem ipsum dolor
timeOccurred	DateTime	The time the event occurred.	2023-01-01T08:00+01:00
source	EntityRef
reportingSystem	EntityRef
fieldPath	FieldPath [n..m]	Field path	[]

JSON representation sample

Alternate offering JSON example

Supplier contact JSON example

Product Order Information Required Event

ProductOrderInformationRequiredEvent

Data type: Event

The notification data structure

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
eventId (1)	string	The identifier of the notification.	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
eventTime (1)	DateTime	Time of the event occurrence.	2023-01-01T08:00+01:00
eventType (1)	string	The type of the notification.
event (1)	ProductOrderInformationRequiredEventPayload
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
description	string	An explanatory of the event.	Lorem ipsum dolor
timeOccurred	DateTime	The time the event occurred.	2023-01-01T08:00+01:00
source	EntityRef
reportingSystem	EntityRef
fieldPath	FieldPath [n..m]	Field path	[]

JSON representation sample

Requested completion date JSON example

Product Order Jeopardy Alert Event

ProductOrderJeopardyAlertEvent

Data type: Event

The notification data structure

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
eventId (1)	string	The identifier of the notification.	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
eventTime (1)	DateTime	Time of the event occurrence.	2023-01-01T08:00+01:00
eventType (1)	string	The type of the notification.
event (1)	ProductOrderJeopardyAlertEventPayload
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
description	string	An explanatory of the event.	Lorem ipsum dolor
timeOccurred	DateTime	The time the event occurred.	2023-01-01T08:00+01:00
source	EntityRef
reportingSystem	EntityRef

JSON representation sample

Order delay JSON example

Product Order Milestone Event

ProductOrderMilestoneEvent

Data type: Event

The notification data structure

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
eventId (1)	string	The identifier of the notification.	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
eventTime (1)	DateTime	Time of the event occurrence.	2023-01-01T08:00+01:00
eventType (1)	string	The type of the notification.
event (1)	ProductOrderMilestoneEventPayload
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
description	string	An explanatory of the event.	Lorem ipsum dolor
timeOccurred	DateTime	The time the event occurred.	2023-01-01T08:00+01:00
source	EntityRef
reportingSystem	EntityRef

JSON representation sample

Point of no return JSON example

Cancel Product Order State Change Event

CancelProductOrderStateChangeEvent

Data type: Event

The notification data structure

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
eventId (1)	string	The identifier of the notification.	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
eventTime (1)	DateTime	Time of the event occurrence.	2023-01-01T08:00+01:00
eventType (1)	string	The type of the notification.
event (1)	CancelProductOrderStateChangeEventPayload
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
description	string	An explanatory of the event.	Lorem ipsum dolor
timeOccurred	DateTime	The time the event occurred.	2023-01-01T08:00+01:00
source	EntityRef
reportingSystem	EntityRef

JSON representation sample

In Progress JSON example

Close Product Order State Change Event

CloseProductOrderStateChangeEvent

Data type: Event

The notification data structure

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
eventId (1)	string	The identifier of the notification.	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
eventTime (1)	DateTime	Time of the event occurrence.	2023-01-01T08:00+01:00
eventType (1)	string	The type of the notification.
event (1)	CloseProductOrderStateChangeEventPayload
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
description	string	An explanatory of the event.	Lorem ipsum dolor
timeOccurred	DateTime	The time the event occurred.	2023-01-01T08:00+01:00
source	EntityRef
reportingSystem	EntityRef

JSON representation sample

Rejected JSON example

Respond Provider Change State Change Event

RespondProviderChangeStateChangeEvent

Data type: Event

The notification data structure

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
eventId (1)	string	The identifier of the notification.	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
eventTime (1)	DateTime	Time of the event occurrence.	2023-01-01T08:00+01:00
eventType (1)	string	The type of the notification.
event (1)	RespondProviderChangeStateChangeEventPayload
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
description	string	An explanatory of the event.	Lorem ipsum dolor
timeOccurred	DateTime	The time the event occurred.	2023-01-01T08:00+01:00
source	EntityRef
reportingSystem	EntityRef

JSON representation sample

In Progress JSON example

Reschedule Product Order State Change Event

RescheduleProductOrderStateChangeEvent

Data type: Event

The notification data structure

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
eventId (1)	string	The identifier of the notification.	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
eventTime (1)	DateTime	Time of the event occurrence.	2023-01-01T08:00+01:00
eventType (1)	string	The type of the notification.
event (1)	RescheduleProductOrderStateChangeEventPayload
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
description	string	An explanatory of the event.	Lorem ipsum dolor
timeOccurred	DateTime	The time the event occurred.	2023-01-01T08:00+01:00
source	EntityRef
reportingSystem	EntityRef

JSON representation sample

Acknowledged JSON example

Add Product Order Information State Change Event

AddProductOrderInformationStateChangeEvent

Data type: Event

The notification data structure

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
eventId (1)	string	The identifier of the notification.	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
eventTime (1)	DateTime	Time of the event occurrence.	2023-01-01T08:00+01:00
eventType (1)	string	The type of the notification.
event (1)	AddProductOrderInformationStateChangeEventPayload
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
description	string	An explanatory of the event.	Lorem ipsum dolor
timeOccurred	DateTime	The time the event occurred.	2023-01-01T08:00+01:00
source	EntityRef
reportingSystem	EntityRef

JSON representation sample

Done JSON example

Amend Product Order State Change Event

AmendProductOrderStateChangeEvent

Data type: Event

The notification data structure

Name	Type	Description	Example
@type (1)	string	When sub-classing, this defines the sub-class Extensible name
eventId (1)	string	The identifier of the notification.	2d7ed5fd-9f62-4211-bc84-357f5f7b80f5
eventTime (1)	DateTime	Time of the event occurrence.	2023-01-01T08:00+01:00
eventType (1)	string	The type of the notification.
event (1)	AmendProductOrderStateChangeEventPayload
@baseType	string	When sub-classing, this defines the super-class
@schemaLocation	string	A URI to a JSON-Schema file that defines additional attributes and relationships
description	string	An explanatory of the event.	Lorem ipsum dolor
timeOccurred	DateTime	The time the event occurred.	2023-01-01T08:00+01:00
source	EntityRef
reportingSystem	EntityRef

JSON representation sample

Rejected JSON example

Validation using Conformance Profile

A Conformance Profile is supplied in the form of a JSON Schema (see tmf622-product-order-fvo.schema.jso).

The following rules are checked:

• Mandatory attribute,
• Mandatory attribute if the optional parent attribute is present,
• Mandatory/Non-mandatory attribute, depending on further conditions

Where a resource is an input into an API (e.g. POST), Mandatory means that the attribute value must be supplied by the API consumer in the input and must not be blank or null

Where a resource is an output from an API (e.g. GET, POST), Mandatory means that the attribute value must be supplied by the API provider in the output and must not be blank or null.