User Guide FIT Product Ordering Management API

AG-FIT 622

Release 2.0.0 (Build 537) 2025-09-15 for review

Release notes

Please see the version history for the list of changes in the last versions.

Version history

Description

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 attribute 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 InflightChangeProductOrder (FIT only, for changing (amend, reschedule, add information, provide a response to an existing provider change Product Order, close) an existing Product Order):

• Creation of an Inflight Change Product Order request
• Retrieval of an Inflight Change Product Order request or a collection of Inflight Change Product Order requests depending on filter criteria
• Notification of events on Inflight Change Product Order
  • Inflight Change Product Order state change

FIT Adaptations

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

InflightChangeProductOrder task resource: added task resource to change an existing Product Order, e.g., rescheduling, addition of optional products, notes and related parties.

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
createInflightChangeProductOrder	POST /inflightChangeProductOrder	Creates an InflightChangeProductOrder
listInflightChangeProductOrder	GET /inflightChangeProductOrder	List or find InflightChangeProductOrder objects
retrieveInflightChangeProductOrder	GET /inflightChangeProductOrder/{id}	Retrieves an InflightChangeProductOrder by ID
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
listenToInflightChangeProductOrderStateChangeEvent	POST /listener/inflightChangeProductOrderStateChangeEvent	Client listener for InflightChangeProductOrderStateChangeEvent

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.
• readyForActivation: NotConnected Order successful. Following order needs to be posted.

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:00+01:00
orderPostedDate (1)	DateTime	Date when the order was posted by the requester	2023-01-01T08:00: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: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:00+01:00
orderIsChargingRelevant	boolean	Boolean amended by the provider defining if the processing of the ProductOrder is charging relevant	false
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:00+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	[]
stateChangeMessage	Message [n..m]	Message 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: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

{
  "$schema" : "https://bitbucket.org/fit-api/fit-api/raw/tmf622_v2.0.0/tmf622/ctk/json-schema/fit-tmf622.schema.json",
  "@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" : "externalOrderId",
    "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.

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
state (1)	TaskStateType
requestDate (1)	DateTime	Date when the task resource was created	2023-01-01T08:00:00+01:00
requestPostedDate (1)	DateTime	Date when the request was posted	2023-01-01T08:00:00+01:00
entity (1)	EntityRef
@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
stateChangeDate	DateTime	The date and time the state changed.	2024-01-01T12:00:00+01:00
stateChangeMessage	Message [n..m]	Message 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	[]
externalId	ExternalIdentifier [n..m]	A reference to an externaly defined object in the context of the Product Order	[]

JSON representation sample

{
  "$schema" : "https://bitbucket.org/fit-api/fit-api/raw/tmf622_v2.0.0/tmf622/ctk/json-schema/fit-tmf622.schema.json",
  "@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",
  "requestDate" : "2022-05-11T11:25:00+02:00",
  "requestPostedDate" : "2022-05-11T10:30:00+02:00",
  "entity" : {
    "@type" : "ProductOrderRef",
    "id" : "388a4963-f168-4603-99e8-477200099d91",
    "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/productOrder/388a4963-f168-4603-99e8-477200099d91"
  },
  "stateChangeDate" : "2022-05-11T11:25:00+02:00",
  "stateChangeMessage" : [ {
    "code" : "code",
    "text" : "acknowledged_Message"
  } ]
}

Inflight Change Product Order task resource

Resource model

Field description

InflightChangeProductOrder

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
state (1)	TaskStateType
requestDate (1)	DateTime	Date when the task resource was created	2023-01-01T08:00:00+01:00
requestPostedDate (1)	DateTime	Date when the request was posted	2023-01-01T08:00:00+01:00
entity (1)	EntityRef
category (1)	array
@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
requestedCompletionDate	DateTime	Rescheduled requested delivery date from the requester perspective	2025-12-24T19:30:00+01:00
closeMessage	Message
stateChangeDate	DateTime	The date and time the state changed.	2024-01-01T12:00:00+01:00
stateChangeMessage	Message [n..m]	Message 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	[]
providerChangeInfo	ProviderChangeInfo
externalId	ExternalIdentifier [n..m]	A reference to an externaly defined object in the context of the Product Order	[]
agreement	AgreementRefOrValue [n..m]	A reference to an agreement defined in the context of the Product Order	[]
note	Note [n..m]	Note	[]
relatedParty	RelatedPartyOrPartyRole [n..m]	Related party	[]
additionalOrderInformation	AdditionalOrderInformation
productOrderItem	ProductOrderItem [n..m]

JSON representation samples

Category reschedule

{
  "$schema" : "https://bitbucket.org/fit-api/fit-api/raw/tmf622_v2.0.0/tmf622/ctk/json-schema/fit-tmf622.schema.json",
  "@type" : "InflightChangeProductOrder",
  "id" : "33359a1e-134f-4b0f-98a8-acc91af5bbee",
  "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/inflightChangeProductOrder/33359a1e-134f-4b0f-98a8-acc91af5bbee",
  "state" : "acknowledged",
  "requestDate" : "2022-07-20T09:00:00+02:00",
  "requestPostedDate" : "2022-07-20T08:00:00+02:00",
  "entity" : {
    "@type" : "ProductOrderRef",
    "id" : "388a4963-f168-4603-99e8-477200099d91",
    "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/productOrder/388a4963-f168-4603-99e8-477200099d91"
  },
  "category" : [ "reschedule", "amend" ],
  "requestedCompletionDate" : "2022-07-20T12:00:00+02:00",
  "stateChangeDate" : "2022-07-20T09:00:00+02:00",
  "stateChangeMessage" : [ {
    "code" : "code",
    "text" : "acknowledged_Message"
  } ],
  "productOrderItem" : [ {
    "@type" : "ProductOrderItem",
    "id" : "1",
    "action" : "modify",
    "requestedTimeSlot" : {
      "@type" : "TimeSlot",
      "validFor" : {
        "startDateTime" : "2022-07-20T08:00:00+02:00",
        "endDateTime" : "2022-07-20T12:00:00+02:00"
      }
    }
  }, {
    "@type" : "ProductOrderItem",
    "id" : "2",
    "action" : "add",
    "productOffering" : {
      "@type" : "ProductOffering",
      "name" : "AUFTRAG_REPARATUR_EL"
    },
    "productOrderItemRelationship" : [ {
      "@type" : "OrderItemRelationship",
      "id" : "1",
      "relationshipType" : "dependsOn"
    } ]
  } ]
}

Category respondProviderChange

{
  "$schema" : "https://bitbucket.org/fit-api/fit-api/raw/tmf622_v2.0.0/tmf622/ctk/json-schema/fit-tmf622.schema.json",
  "@type" : "InflightChangeProductOrderStateChangeEvent",
  "eventId" : "e25523f1-a75d-4e72-b05a-3d0d7dca5862",
  "eventTime" : "2022-05-11T10:36:00+02:00",
  "eventType" : "InflightChangeProductOrderStateChangeEvent",
  "event" : {
    "inflightChangeProductOrder" : {
      "@type" : "InflightChangeProductOrder",
      "id" : "892cfa45-fca3-488d-8a7c-2883923f820e",
      "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/inflightChangeProductOrder/892cfa45-fca3-488d-8a7c-2883923f820e",
      "state" : "inProgress",
      "requestDate" : "2022-05-11T10:35:00+02:00",
      "requestPostedDate" : "2022-05-11T10:35:00+02:00",
      "entity" : {
        "@type" : "ProductOrderRef",
        "id" : "596d7fa0-981f-4b98-bcf5-e9b2955776f4",
        "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/productOrder/596d7fa0-981f-4b98-bcf5-e9b2955776f4"
      },
      "category" : [ "respondProviderChange" ],
      "stateChangeDate" : "2022-05-11T10:36:00+02:00",
      "stateChangeMessage" : [ {
        "code" : "code",
        "text" : "inProgress_Message"
      } ],
      "stateChangeHistory" : [ {
        "@type" : "StateChange",
        "stateChangeDate" : "2022-05-11T10:35:00+02:00",
        "state" : "acknowledged"
      } ],
      "providerChangeInfo" : {
        "@type" : "ProviderChangeInfo",
        "approval" : true
      }
    }
  }
}

Category close

{
  "$schema" : "https://bitbucket.org/fit-api/fit-api/raw/tmf622_v2.0.0/tmf622/ctk/json-schema/fit-tmf622.schema.json",
  "@type" : "InflightChangeProductOrder",
  "id" : "a32b3fee-e1f0-4b3b-9fee-3907a8bdaac1",
  "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/inflightChangeProductOrder/a32b3fee-e1f0-4b3b-9fee-3907a8bdaac1",
  "state" : "acknowledged",
  "requestDate" : "2022-05-25T10:30:00+02:00",
  "requestPostedDate" : "2022-05-11T10:30:00+02:00",
  "entity" : {
    "@type" : "ProductOrderRef",
    "id" : "388a4963-f168-4603-99e8-477200099d91",
    "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/productOrder/388a4963-f168-4603-99e8-477200099d91"
  },
  "category" : [ "close" ],
  "closeMessage" : {
    "code" : "0015",
    "text" : "Endkunde hat die Bereitstellung der Leistung bestätigt. Anschluss störungsfrei in Betrieb."
  },
  "stateChangeDate" : "2022-05-25T10:30:00+02:00",
  "stateChangeMessage" : [ {
    "code" : "code",
    "text" : "acknowledged_Message"
  } ]
}

Category add

{
  "$schema" : "https://bitbucket.org/fit-api/fit-api/raw/tmf622_v2.0.0/tmf622/ctk/json-schema/fit-tmf622.schema.json",
  "@type" : "InflightChangeProductOrder",
  "id" : "d1317bb6-969a-4da7-be54-2d3760e48fee",
  "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/inflightChangeProductOrder/d1317bb6-969a-4da7-be54-2d3760e48fee",
  "state" : "acknowledged",
  "requestDate" : "2022-07-20T09:00:00+02:00",
  "requestPostedDate" : "2022-07-20T08:00:00+02:00",
  "entity" : {
    "@type" : "ProductOrderRef",
    "id" : "388a4963-f168-4603-99e8-477200099d91",
    "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/productOrder/388a4963-f168-4603-99e8-477200099d91"
  },
  "category" : [ "add" ],
  "stateChangeDate" : "2022-07-20T09:00:00+02:00",
  "stateChangeMessage" : [ {
    "code" : "code",
    "text" : "acknowledged_Message"
  } ],
  "note" : [ {
    "@type" : "InstallationInstruction",
    "text" : "zweimal klingeln"
  } ],
  "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"
    }
  } ]
}

Category amend

{
  "$schema" : "https://bitbucket.org/fit-api/fit-api/raw/tmf622_v2.0.0/tmf622/ctk/json-schema/fit-tmf622.schema.json",
  "@type" : "InflightChangeProductOrder",
  "id" : "f8d80f8c-7f70-4dca-aa25-a3321d50685d",
  "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/inflightChangeProductOrder/f8d80f8c-7f70-4dca-aa25-a3321d50685d",
  "state" : "acknowledged",
  "requestDate" : "2022-07-20T09:00:00+02:00",
  "requestPostedDate" : "2022-07-20T08:00:00+02:00",
  "entity" : {
    "@type" : "ProductOrderRef",
    "id" : "388a4963-f168-4603-99e8-477200099d91",
    "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/productOrder/388a4963-f168-4603-99e8-477200099d91"
  },
  "category" : [ "amend" ],
  "stateChangeDate" : "2022-07-20T09:00:00+02:00",
  "stateChangeMessage" : [ {
    "code" : "code",
    "text" : "acknowledged_Message"
  } ],
  "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 InflightChangeProductOrder:

• InflightChangeProductOrderStateChangeEvent

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:00+01:00
eventType (1)	string	The type of the notification.
@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:00+01:00
source	EntityRef	Source Entity described by EntityRef	null
reportingSystem	EntityRef	Reporting System described by EntityRef	null
event	ProductOrderCreateEventPayload

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:00+01:00
eventType (1)	string	The type of the notification.
@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:00+01:00
source	EntityRef	Source Entity described by EntityRef	null
reportingSystem	EntityRef	Reporting System described by EntityRef	null
event	ProductOrderStateChangeEventPayload	The event payload linked to the involved resource object	null

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:00+01:00
eventType (1)	string	The type of the notification.
@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:00+01:00
source	EntityRef	Source Entity described by EntityRef	null
reportingSystem	EntityRef	Reporting System described by EntityRef	null
fieldPath	FieldPath [n..m]	Field path	[]
event	ProductOrderAttributeValueChangeEventPayload	The event payload linked to the involved resource object	null

JSON representation sample

Alternate offering JSON example

Seller 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:00+01:00
eventType (1)	string	The type of the notification.
@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:00+01:00
source	EntityRef	Source Entity described by EntityRef	null
reportingSystem	EntityRef	Reporting System described by EntityRef	null
fieldPath	FieldPath [n..m]	Field path	[]
event	ProductOrderInformationRequiredEventPayload	The event payload linked to the involved resource object	null

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:00+01:00
eventType (1)	string	The type of the notification.
@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:00+01:00
source	EntityRef	Source Entity described by EntityRef	null
reportingSystem	EntityRef	Reporting System described by EntityRef	null
event	ProductOrderJeopardyAlertEventPayload	The event payload linked to the involved resource object	null

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:00+01:00
eventType (1)	string	The type of the notification.
@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:00+01:00
source	EntityRef	Source Entity described by EntityRef	null
reportingSystem	EntityRef	Reporting System described by EntityRef	null
event	ProductOrderMilestoneEventPayload	The event payload linked to the involved resource object	null

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:00+01:00
eventType (1)	string	The type of the notification.
@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:00+01:00
source	EntityRef	Source Entity described by EntityRef	null
reportingSystem	EntityRef	Reporting System described by EntityRef	null
event	CancelProductOrderStateChangeEventPayload	The event payload linked to the involved resource object	null

JSON representation sample

Inflight Change Product Order State Change Event

InflightChangeProductOrderStateChangeEvent

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:00+01:00
eventType (1)	string	The type of the notification.
@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:00+01:00
source	EntityRef	Source Entity described by EntityRef	null
reportingSystem	EntityRef	Reporting System described by EntityRef	null
event	InflightChangeProductOrderStateChangeEventPayload	The event payload linked to the involved resource object	null

JSON representation sample for close product order

Rejected JSON example

JSON representation sample for respond provider change

In Progress JSON example

JSON representation sample for reschedule product order

Acknowledged JSON example

JSON representation sample for add product information

Done JSON example

JSON representation sample for amend product order

Rejected JSON example

Validation using Conformance Profile

A Conformance Profile is supplied in the form of a JSON Schema (see fit-tmf622.schema.json).

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.