You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Remember the following Uniform Contract:

Operation on Entities

Uniform API Operation

Description

Query Entities

GET Resource

GET must be used to retrieve a representation of a resource.

Create Entity

POST Resource

POST must be used to create a new resource

Partial Update of an Entity

PATCH Resource

PATCH must be used to partially update a resource

Complete Update of an Entity

PUT Resource

PUT must be used to completely update a resource identified by its resource URI

Remove an Entity

DELETE Resource

DELETE must be used to remove a resource

Execute an Action on an Entity

POST on TASK Resource

POST must be used to execute Task Resources

Other Request Methods

POST on TASK Resource

GET and POST must not be used to tunnel other request methods.


Filtering and attribute selection rules are described in the TMF REST Design Guidelines.
Notifications are also described in a subsequent section.

GET /orderManagement/productOrder/{ID}

Note that collections can be retrieved via GET /orderManagement/productOrder with no {ID}
Description :
This operation is used to retrieve order information using the ID
Attribute selection is enabled on all first level attributes but not on inner classes.
Attribute selection may optionally be enabled on all attributes and inner classes.
Behavior :

  • Return status codes
    • 200 OK - the request was successful
    • 404 Not found - the supplied ID does not match a known productOrder


Use case : Get a specific order based on its ID

REQUEST

GET /orderManagement/productOrder/42
Accept: application/json

RESPONSE

200
Content-Type: application/json

{   "id":"42",   "href":"http://serverlocation:port/orderManagement/productOrder/42",   "externalId":"NiceNameForTheConsumer_42",   "priority":"1",   "description":"A wonderful 42 order for brand new products",   "category":"residential",   "state":"InProgress",   "orderDate":"2013-04-12T16:42:23-04:00",   "completionDate":"2013-04-19T16:42:23-04:00",   "requestedStartDate":"2013-04-12T16:42:23-04:00",   "requestedCompletionDate":"2013-04-19T16:42:23-04:00",   "expectedCompletionDate":"2013-04-19T16:42:23-04:00",   "notificationContact":"[email protected]",   "note":[      {          "text":"A free text detailing the note",         "date":"2013-04-12T16:42:23-04:00",         "author":"name"      }   ],   "relatedParty":[      {         "role":"customer",         "id":"345221",         "href":"http://serverlocation:port/partyManagement/customer/345221"         "name":"John Doe"      },      {         "role":"partner",         "id":"42",         "href":"http://serverlocation:port/partyManagement/partner/42"      },      {         "role":"seller",         "id":"4563",         "href":"http://serverlocation:port/partnerManagement/partner/4563"      }   ],   "orderItem":[      {         "id":"1",         "action":"add",         "state":"Acknowledged",         "billingAccount":[{               "id":"123456",               "href":"http://serverlocation:port/billingManagement/billingAccount/123456"         }],
         "appointment":"http://www.doodle.com/1WCV5647438",         "productOffering":{            "id":"42",            "href":"http: //serverlocation: port/catalogManagement/productOffering/42"         },         "product":{         "place":{            "href":"http://map.google.com/.../1234112GDE",            "role":"DeliveryPlace"         },            "productCharacteristic":[               {                   "name":"Colour",                  "value":"White"               },               {                  "name":"Memory",                  "value":"16"               }            ]         }      },      {         "id":"2",         "action":"modify",         "state":"InProgress",         "productOffering":{            "id":"43",            "href":"http: //serverlocation: port/catalogManagement/productOffering/43"         },         "product":{            "id":"456",            "href":"http: //serverlocation: port/inventoryManagement/product/456",            "productCharacteristic":[               {                  "name":"anotherCharacteristic",                  "value":"itsValue"               }            ],            "relatedParty":[               {                  "role":"user",                  "id":"5667443",                  "href":"http://serverlocation:port/partyManagement/user/5667443"                  "name":"Jimmy Doe"               }            ]         }      },      {         "id":"3",         "action":"add",         "state":"InProgress",         "billingAccount":[{               "id":"123456",               "href":"http://serverlocation:port/billingManagement/billingAccount/123456"         }],          "productOffering":{            "id":"51",            "href":"http: //serverlocation: port/catalogManagement/productOffering/51"         },         "product":{            "id":"511",            "href":"http: //serverlocation: port/inventoryManagement/product/456",            "productCharacteristic":[               {                  "name":"anotherCharacteristic",                  "value":"itsValue"               }            ],            "productRelationship":[               {                  "type":"reliesOn",                  "product":{                     "productCharacteristic":[                        {                           "name":"MSISDN",                           "value":"003467488299002"                        }                     ]                  }               }            ]         }      },      {         "id":"4",         "action":"add",         "state":"InProgress",         "billingAccount":[{               "id":"1789",               "href":"http://serverlocation:port/billingManagement/billingAccount/1789"         }],         "productOffering":{            "id":"44",            "href":"http://serverlocation:port/catalogManagement/productOffering/Bundle44",            "bundledProductOffering":[               {                     "id":" BundledPSTN444",                     "href":"http://serverlocation:port/catalogManagement/productOffering/BundledPSTN444"         },
{                     "id":" Bundled Mobile443",                     "href":"http://serverlocation:port/catalogManagement/productOffering/BundledMobile443"         }            ]         },         "product":{            "productRelationship":[               {                  "type":"bundled",                  "product":{                     "productCharacteristic":[                        {                           "name":"PSTNNumber",                           "value":"003427488299002"                        }                     ]                  }               },               {                  "type":"bundled",                  "product":{                     "productCharacteristic":[                        {                           "name":"MobileNumber",                           "value":"003464553000300"                        }                     ]                  }               }            ]         }      }   ]}



GET /orderManagement/productOrder/?{field selector}&{filtering expression}

Description :
This operation is used to retrieve order information using filter criteria.
Filtering selection is enabled on all first level attributes but not on inner classes with the exception of relatedParties.
Filtering may optionally be enabled on all attributes and inner classes.
Attribute selection is enabled on all first level attributes but not on inner classes.
Attribute selection may optionally be enabled on all attributes and inner classes.
Behavior :

  • Return status codes
    • 200 OK - the request was successful (includes situation in which no orders matched supplied criteria)
    • 400 Bad Request - error


Use case : Get all the orders for a given customer that were completed before a specified date

REQUEST

GET /orderManagement/productOrder?relatedParty.role=customer& relatedParty.id=345221&completionDate.lt=2013-09-10 T00:00:00 -04:00

Accept: application/json

RESPONSE

200
Content-Type: application/json

[ {   "id":"42",   "href":"http://serverlocation:port/orderManagement/productOrder/42",   "externalId":"NiceNameForTheConsumer_42",   "priority":"1",   "description":"A wonderful 42 order for brand new products",   "category":"residential",   "state":"Completed",   "orderDate":"2013-04-12T16:42:23-04:00",   "completionDate":"2013-04-19T16:42:23-04:00",   "requestedStartDate":"2013-04-12T16:42:23-04:00",   "requestedCompletionDate":"2013-04-19T16:42:23-04:00",   "expectedCompletionDate":"2013-04-19T16:42:23-04:00",   "notificationContact":"[email protected]",   "note":[      {         "text":"A free text detailing the note",         "date":"2013-04-12T16:42:23-04:00",         "author":"name"      }    ],   "relatedParty":[      {         "role":"customer",         "id":"345221",         "href":"http://serverlocation:port/partyManagement/customer/345221"         "name":"John Doe"      },      {         "role":"partner",         "id":"42",         "href":"http://serverlocation:port/partyManagement/partner/42"      },      {         "role":"seller",         "id":"4563",         "href":"http://serverlocation:port/partnerManagement/partner/4563"      }   ],   "orderItem":[      {         "id":"1",         "action":"add",         "state":"Completed",         "billingAccount":[{               "id":"123456",               "href":"http://serverlocation:port/billingManagement/billingAccount/123456"         }],
         "appointment":"http://www.doodle.com/1WCV5647438",         "productOffering":{            "id":"42",            "href":"http: //serverlocation: port/catalogManagement/productOffering/42"         },         "product":{         "place":{            "href":"http://map.google.com/.../1234112GDE",            "role":"DeliveryPlace"         },            "productCharacteristic":[               {                  "name":"Colour",                  "value":"White"               },               {                   "name":"Memory",                  "value":"16"               }            ]         }      },      {         "id":"2",         "action":"modify",         "state":"Completed",         "productOffering":{            "id":"43",            "href":"http: //serverlocation: port/catalogManagement/productOffering/43"         },         "product":{            "id":"456",            "href":"http: //serverlocation: port/inventoryManagement/product/456",            "productCharacteristic":[               {                  "name":"anotherCharacteristic",                  "value":"itsValue"               }            ],            "relatedParty":[               {                  "role":"user",                  "id":"5667443",                  "href":"http://serverlocation:port/partyManagement/user/5667443"                  "name":"Jimmy Doe"               }            ]         }      },      {         "id":"3",         "action":"add",         "state":"Completed",         "billingAccount":[{               "id":"123456",               "href":"http://serverlocation:port/billingManagement/billingAccount/123456"         }],         "productOffering":{            "id":"51",            "href":"http: //serverlocation: port/catalogManagement/productOffering/51"         },          "product":{            "id":"511",            "href":"http: //serverlocation: port/inventoryManagement/product/456",            "productCharacteristic":[               {                  "name":"anotherCharacteristic",                  "value":"itsValue"               }            ],            "productRelationship":[               {                  "type":"reliesOn",                  "product":{                     "productCharacteristic":[                        {                           "name":"MSISDN",                           "value":"003467488299002"                        }                     ]                  }               }            ]         }      },      {         "id":"4",         "action":"add",         "state":"Completed",         "billingAccount":[{               "id":"1789",               "href":"http://serverlocation:port/billingManagement/billingAccount/1789"         }],         "productOffering":{            "id":"44",            "href":"http://serverlocation:port/catalogManagement/productOffering/Bundle44",            "bundledProductOffering":[               {                     "id":" BundledPSTN444",                     "href":"http://serverlocation:port/catalogManagement/productOffering/BundledPSTN444"         },
{                     "id":" Bundled Mobile443",                     "href":"http://serverlocation:port/catalogManagement/productOffering/BundledMobile443"         }             ]         },         "product":{            "productRelationship":[               {                  "type":"bundled",                  "product":{                     "productCharacteristic":[                        {                           "name":"PSTNNumber",                           "value":"003427488299002"                        }                     ]                  }               },               {                  "type":"bundled",                  "product":{                     "productCharacteristic":[                        {                           "name":"MobileNumber",                           "value":"003464553000300"                        }                     ]                  }               }            ]         }      }   ]}]



PATCH /orderManagement/productOrder/{ID}

Description :
This operation is used to modify orders and/or their items.
Behavior :

  • Return status codes
    • 200 OK - the request was successful
    • 400 Bad Request - error


Attribute name

Patchable

Rule

id

No

 

href

No

 

externalID

No

 

state

Yes

To manage the order delivery process : InProgress (start process), Held / Pending (suspend process)
Influence the orderItem states

priority

Yes

 

category

Yes

 

orderDate

No

 

requestedStartDate

Yes

Only when order is in "Acknowledged" state – delivery process not started

completionDate

No

 

requestedCompletionDate

Yes

Only when order is in "Acknowledged" state – delivery process not started

expectedCompletionDate

Yes

 

notificationContact

Yes

 

note

Yes

 

relatedParty

Yes

Only when order is in "Acknowledged" state – delivery process not started

orderItem.id

No

 

orderItem.action

No

 

orderItem.state

Yes

To manage the order item delivery process : InProgress (start sub process), Held / Pending (suspend sub process)
Influence the order states

orderItem.billingAccount

Yes

Only when order is in "Acknowledged" state – delivery process not started

orderItem.productOffering

Yes

Only when order is in "Acknowledged" state – delivery process not started

orderItem.product

Yes

Only when order item is in "Acknowledged" or "Pending" state – delivery process not started or suspended

orderItem.product.place

Yes

Only when order item is in "Acknowledged" or "Pending" state – delivery process not started or suspended

orderItem.appointment

Yes

Only when order item is in "Acknowledged" or "Pending" state – delivery process not started or suspended


Further document any rules that must be implemented when patching attributes.

Rule name

Rule/Pre Condition/Side Effects/Post Conditons

State patches

When patching an order state to :

  • "Pending" / "Held" : all "InProgress" order items SHOULD be set to "Pending" / "Held"
  • "InProgress" :
    • all "Acknowledged" order items MUST be set to "InProgress"
    • all "Pending"/"Held" order items MAY be set to "InProgress"

      When patching an order item state to :
  • "Pending" / "Held" : the order state itself SHOULD be set to "Pending" / "Held"


Use case : Resume order
Note : Suspend would be the same request using the "Pending" state.

REQUEST

PATCH orderManagement/productOrder/42
Content-type: application/json

{   "state":"InProgress"}

RESPONSE

201
Content-Type: application/json

{   "id":"42",   "href":"http://serverlocation:port/orderManagement/productOrder/42",   "externalId":"NiceNameForTheConsumer_42",   "priority":"1",   "description":"A wonderful 42 order for brand new products",   "category":"residential",   "state":"InProgress",   "orderDate":"2013-04-12T16:42:23-04:00",   "completionDate":"2013-04-19T16:42:23-04:00",   "requestedStartDate":"2013-04-12T16:42:23-04:00",   "requestedCompletionDate":"2013-04-19T16:42:23-04:00",   "expectedCompletionDate":"2013-04-19T16:42:23-04:00",   "notificationContact":"[email protected]",   "note":[      {         "text":"A free text detailing the note",          "date":"2013-04-12T16:42:23-04:00",         "author":"name"      }   ],   "relatedParty":[      {         "role":"customer",         "id":"345221",         "href":"http://serverlocation:port/partyManagement/customer/345221"         "name":"John Doe"      },      {         "role":"partner",         "id":"42",         "href":"http://serverlocation:port/partyManagement/partner/42"      },      {         "role":"seller",         "id":"4563",         "href":"http://serverlocation:port/partnerManagement/partner/4563"      }   ],   "orderItem":[      {         "id":"1",         "action":"add",         "state":"InProgress",         "billingAccount":[{               "id":"123456",               "href":"http://serverlocation:port/billingManagement/billingAccount/123456"         }],
         "appointment":"http://www.doodle.com/1WCV5647438",         "productOffering":{            "id":"42",            "href":"http: //serverlocation: port/catalogManagement/productOffering/42"         },         "product":{         "place":{            "href":"http://map.google.com/.../1234112GDE",            "role":"DeliveryPlace"         },            "productCharacteristic":[               {                  "name":"Colour",                   "value":"White"               },               {                  "name":"Memory",                  "value":"16"               }            ]         }      },      {         "id":"2",         "action":"modify",         "state":"InProgress",         "productOffering":{            "id":"43",            "href":"http: //serverlocation: port/catalogManagement/productOffering/43"         },         "product":{            "id":"456",            "href":"http: //serverlocation: port/inventoryManagement/product/456",            "productCharacteristic":[               {                  "name":"anotherCharacteristic",                  "value":"itsValue"               }            ],            "relatedParty":[               {                  "role":"user",                  "id":"5667443",                  "href":"http://serverlocation:port/partyManagement/user/5667443"                  "name":"Jimmy Doe"               }            ]         }      },      {         "id":"3",         "action":"add",         "state":"InProgress",         "billingAccount":[{               "id":"123456",               "href":"http://serverlocation:port/billingManagement/billingAccount/123456"         }],         "productOffering":{             "id":"51",            "href":"http: //serverlocation: port/catalogManagement/productOffering/51"         },         "product":{            "id":"511",            "href":"http: //serverlocation: port/inventoryManagement/product/456",            "productCharacteristic":[               {                  "name":"anotherCharacteristic",                  "value":"itsValue"               }            ],            "productRelationship":[               {                  "type":"reliesOn",                  "product":{                     "productCharacteristic":[                        {                           "name":"MSISDN",                           "value":"003467488299002"                        }                     ]                  }               }            ]         }      },      {         "id":"4",         "action":"add",         "state":"InProgress",         "billingAccount":[{               "id":"1789",               "href":"http://serverlocation:port/billingManagement/billingAccount/1789"         }],         "productOffering":{            "id":"44",            "href":"http://serverlocation:port/catalogManagement/productOffering/Bundle44",            "bundledProductOffering":[               {                     "id":" BundledPSTN444",                     "href":"http://serverlocation:port/catalogManagement/productOffering/BundledPSTN444"         },
{                      "id":" Bundled Mobile443",                     "href":"http://serverlocation:port/catalogManagement/productOffering/BundledMobile443"         }            ]         },         "product":{            "productRelationship":[               {                  "type":"bundled",                  "product":{                     "productCharacteristic":[                        {                           "name":"PSTNNumber",                           "value":"003427488299002"                        }                     ]                  }               },               {                  "type":"bundled",                  "product":{                     "productCharacteristic":[                        {                           "name":"MobileNumber",                           "value":"003464553000300"                        }                     ]                  }               }            ]         }      }   ]}



POST orderManagement/productorder

Description:
This operation is used to create a new order.
The mandatory attributes for the creation are :

  • relatedParties.role and reference to identify at least the customer
  • at least one orderItem with :
    • an action
    • a productOffering

Behavior :

  • Return status codes
    • 201 Created - the request was successful
    • 400 Bad Request – error


ID Management :
POST should be used without specifying the id and the href, the OM system is in charge of generating the id + href for the ProductOrder.
When performing a POST, these are the allowed attributes (all Product Order attributes that are not in that list MUST NOT be used during POST, they are calculated/defined by the OM system) :

Attribute name

Mandatory

Default

Rule

externalID

N

N/A

 

state

N

"Acknowledged"

 

priority

N

4 (the lowest)

 

Description

N

N/A

 

category

N

"uncategorized"

 

requestedStartDate

N

No specified default value

 

requestedCompletionDate

N

No specified default value

 

notificationContact

N

No specified default value

 

note

N

No specified default value

 

relatedParty

Y

 

They must be at least a defined party linked to the order (Customer, …)

orderItem.id

Y

 

 

orderItem.action

Y

 

 

orderItem.state

N

"Acknowledged"

 

orderItem.billingAccount

Y

 

 

orderItem.productOffering

N

 

The productOffering may not be useful when doing a "modify" or "delete" on an owned product

orderItem.product

Y

 

 

orderItem.product.place

N

 

 

orderItem.appointment

N

 

 


  • Further specify any rules on the creation of the entity

    Rule name

    Rule

    POST Mandatory attributes within product Order

      • Within "billingAccount"
      • id AND/OR href
    • Within "note"
      • text
    • Within "relatedParty"
      • id AND/OR href AND/OR name
      • role|

        POST Mandatory attributes within product Order item

          • Within "place"
      • Role
      • id AND/OR href
    • Within "productOffering"
      • id AND/OR href
    • Within "product"
      • Depends on the order item "action", cf. rule below|

        POST Mandatory attributes within product (in each order item)

          • If orderItem.action = "add" :
      • productCharacteristics
    • If orderItem.action = "modify"
      • id AND/OR href
    • If orderItem.action = "delete"
      • id AND/OR href|

        REQUEST

        POST /orderManagement/productOrder
        Content-type: application/json

        {   "note":[      {         "text":"A free text detailing the note"      }   ],   "relatedParty":[      {         "role":"customer",         "id":"345221",          "href":"http://serverlocation:port/partyManagement/customer/345221",          "name":"John Doe"      },      {         "role":"seller",          "id":"4563",          "href":"http://serverlocation:port/partnerManagement/partner/4563"      }   ],   "orderItem":[      {         "id":"1",         "action":"add",          "billingAccount":[{                "id":"1789",                "href":"http://serverlocation:port/billingManagement/billingAccount/1789"          }],          "productOffering":{             "id":"42",             "href":"http: //serverlocation: port/catalogManagement/productOffering/42"         },         "product":{            "productCharacteristic":[               {                  "name":"Colour",                  "value":"White"                },               {                  "name":"Memory",                  "value":"16"               }            ]         }      },      {         "id":"2",         "action":"modify",         "product":{             "id":"456",             "href":"http: //serverlocation: port/inventoryManagement/product/456",            "relatedParty":[               {                  "role":"user",                  "id":"5667443",                   "href":"http://serverlocation:port/partyManagement/user/5667443",                   "name":"Jimmy Doe"               }            ]         }      },      {         "id":"3",         "action":"delete",         "product":{             "id":"456",             "href":"http: //serverlocation: port/inventoryManagement/product/456"         }      }   ]}

        RESPONSE

        201
        Content-Type: application/json

        {   "id":"42",   "href":"http://serverlocation:port/orderManagement/productOrder/42",   "priority":"4",   "category":"uncategorized",    "state":"Acknowledged",   "orderDate":"2013-04-12T16:42:23-04:00",   "expectedCompletionDate":"2013-04-19T16:42:23-04:00",   "note":[      {         "text":"A free text detailing the note"      }   ],    "relatedParty":[      {         "role":"customer",         "id":"345221",          "href":"http://serverlocation:port/partyManagement/customer/345221"          "name":"John Doe"      },      {         "role":"seller",         "id":"4563",         "href":"http://serverlocation:port/partnerManagement/partner/4563"      }   ],    "orderItem":[      {         "id":"1",         "action":"add",         "state":"Acknowledged",          "billingAccount":[{               "id":"1789",                "href":"http://serverlocation:port/billingManagement/billingAccount/1789"          }],          "productOffering":{             "id":"42",             "href":"http: //serverlocation: port/catalogManagement/productOffering/42"         },         "product":{            "productCharacteristic":[               {                  "name":"Colour",                  "value":"White"               },               {                  "name":"Memory",                  "value":"16"               }            ]         }      },      {         "id":"2",         "action":"modify",         "state":"Acknowledged",          "product":{            "id":"456",             "href":"http: //serverlocation: port/inventoryManagement/product/456",            "relatedParty":[               {                  "role":"user",                  "id":"5667443",                   "href":"http://serverlocation:port/partyManagement/user/5667443",                   "name":"Jimmy Doe"               }            ]         }      },       {         "id":"3",         "action":"delete",         "state":"Acknowledged",         "product":{             "id":"456",             "href":"http: //serverlocation: port/inventoryManagement/product/456"         }      }   ]}


        DELETE orderManagement/productorder/{ID}

        This operation is used to delete a managed entity or a product order entirely.
        Warning : it should only be used for administration matters
        Description :
        This operation is used to delete an order.
        The only usable and also mandatory attributes for the deletion are id AND/OR href.
        Behavior :
  • Returns HTTP/1.1 status code 200 if the request was successful.
  • 404 if the product order does not exist
  • 403 if the operation is forbidden

    REQUEST

    DELETE /orderManagement/productOrder/5868839

    RESPONSE

    200




  • No labels