Fallout Exception Management Rest APIs V2.0 (Cloud Native Only)

Fallout Exception Management Rest API Versions

The Fallout Exception Management APIs are versioned. The endpoint URL builds using the version information. For example:

https://serverRoot/fallout/v2.0/falloutException

For more information on which version you should use, refer to the Manage Fallout Exception section of the REST API Reference for Oracle Communications Order and Service Management Cloud Native.

Version History

The following table details the operations in the available versions of the fallout exception management REST API.

Table 5-1 Version History

Version	Details
V2.0	POST operations on the Fallout Exception Resource. Enhanced GET operations with new response attributes (taskStatuses, lastUpdatedDate and recentAction)
V1	GET operations on the Fallout Exception Resource.

Version

Details

V2.0

POST operations on the Fallout Exception Resource.

Enhanced GET operations with new response attributes (taskStatuses, lastUpdatedDate and recentAction)

V1

GET operations on the Fallout Exception Resource.

Fallout Exception Lifecycle

The following diagram illustrates the fallout exception state lifecycle changes when actions are submitted using the Fallout Exception Management REST APIs.

Figure 5-1 Fallout Exception Lifecycle

Description of "Figure 5-1 Fallout Exception Lifecycle"

Support for Filtering, Grouping and Ordering of Fallout Exception Objects

You can use the GET operation for generating a list of fallout exception objects. These lists provide the details of the objects in fallout exception using the following capabilities:

Filtering
Grouping
Ordering

Filtering and Attribute Selection Rules

The GET operation generates a list of the objects in fallout exception using the filtration and attribute selection capabilities.

This capability filters the fallout exception objects. Wildcard search supports the customerName and orderType fields only.

Any of the following can be provided using the filterBy parameter:

contains (field,'searchstring')
startswith (field,'searchstring')
endswith (field,'searchstring')

Wildcard search for multiple capabilities is also supported.

For example:

GET /falloutException?filterBy=contains(customerName,'ABC') Example: GET /falloutException?filterBy=contains(customerName,'ABC')&filterBy=contains(orderType,'Service')&fields=customerName,orderId,state,requestedCompletionDate

Grouping

The grouping capability returns the aggregated fallout exception objects with total fallout exceptions per order and other aggregated details. Fallout exceptions can only be grouped based on the orderId.

For example:

GET /falloutException?groupBy=orderId

Ordering

The Ordering capability returns the objects in fallout exception in a sorted order.

The following are valid fields for the orderBy parameter when it is used with the groupBy parameter:

orderId
customerName
orderType
requestedCompletionDate
creationDate
externalId
totalFalloutExceptionPerOrder

The following are valid fields for the orderBy parameter when it is used without the groupBy parameter:

timestamp
errorId
productNames
taskName

For example:

GET /falloutException?orderBy=errorId&sort=asc

Note:

By default, the objects will be sorted in descending order.
GET /falloutException?groupBy=orderId&orderBy=creationDate&sort=desc

Additional Query Fields

The following table describes the querying fields you can use for the GET operation to find the list of the objects in fallout exception.

Table 5-2 Additional Query Fields

Query Field	Description	Example
customerName	Retrieves fallout exceptions for a given customer name. You can provide multiple customer names.	`GET /falloutException?customerName=abcd&customerName=xyz`
fromRequestedCompletionDate	The start date for the requested completion date. You must use this with toRequestedCompletionDate.	`GET /falloutException?fromRequestedCompletionDate=2016-11-15&toRequestedCompletionDate=2016-11-20`
fromfalloutCreationDate	The start date for the report. You must use this with tofalloutCreationDate.	`GET /falloutException?fromfalloutCreationDate=2016-11-15&tofalloutCreationDate=2016-11-20`
orderId	Retrieves fallout exceptions for an orderId. You can also provide multiple orderIds.	`GET /falloutException?orderId=12345 or GET /falloutException?orderId=12345&orderId=3312`
orderType	Retrieves data based on orderType (this is shown as Reference Number in the Fallout Order Operations Dashboard). You can also provide multiple states.	`GET /falloutException?orderType=Product or GET /falloutException?orderType=Product&orderType=Service`
overdue	Retrieves fallout exceptions for orders that are overdue based on the requested completion date.	`GET /falloutException?overdue=true`
toRequestedCompletionDate	The end date for the report. You must use this with fromRequestedCompletionDate.	`GET /falloutException?fromRequestedCompletionDate=2016-11-15&toRequestedCompletionDate=2016-11-20`
tofalloutCreationDate	The end date for the report. You must use this with fromfalloutCreationDate.	`GET /falloutException?fromfalloutCreationDate=2016-11-15&tofalloutCreationDate=2016-11-20`

Supported Fallout Actions

The following actions can be submitted using the Fallout Exception Management REST API endpoint submitFalloutAction:

Force Complete Task: The task will be marked as Complete with the task status provided by you. This resolves the fallout exception. You have to take care of the required data updates that are needed to perform the force complete prior to submitting the action.
Retry Task: The task is retried and the fallout exception is cleared. If the Retry is successful, the task completes. If the Retry runs into problems, the cartridge code can raise a new fallout exception.
Cancel Order: This operation cancels an order. All outstanding work items associated with the order are deleted, and all complete work items associated with the order are compensated (undone).
Fail Order: This results in the entire OSM order failing and triggers an update to the final TMF state in case of TMF orders. The fallout exception is resolved automatically, marked with the action code Fail.
Abort Order: This operation tells OSM to stop working on the selected order without triggering any further work.

API Operations

The table below lists the supported endpoints in the Simplified Fallout Exception Management. If an endpoint is not listed, then it is not supported.

Table 5-3 Supported Fallout Endpoints

API Endpoint	API Operation	Description
/falloutException	GET	List or find fallout exceptions.
/falloutException/{id}	GET	Retrieve a fallout exception using its ID.
/falloutException/{id}/submitFalloutAction	POST	Submit a given fallout action on the fallout exception.
/falloutException/submitFalloutAction	POST	Submit a given fallout action on the fallout order.

Authentication and Authorization

The Fallout Exception Management REST APIs are secured with OpenID connect (OIDC) that has been configured for the TMF Rest APIs.

For further details about authentication and authorization, refer to the section Using TMF REST APIs (Cloud Native Only).

For further details about the OIDC, refer to the section About OSM Authentication and Authorization Methods of the Security Guide.

Constructing the Endpoint

This section provides the details for using the GET and POST endpoints for the Fallout Exception API.

GET Endpoints

The following table shows the API attributes and example values for listing or finding the OSM Fallout Exception details:

Table 5-4 API Attributes for Listing or Finding Fallout Exception Details

API Attribute	Example Value
API Endpoint URL	`http://hostname:port/orchestration/sr/quick/falllout/v2.0/falloutException` where `hostname` and `port` are the access details of the Kubernetes cluster exposed by your Ingress Controller or Load Balancer.
Request Type	GET.
Request Header	There are no request headers for this operation.
Request Body	There's no request body for this operation.
Authentication	`Authorization:Bearer access-token` (The key-value is added as a header).
Query Parameters	Query parameters are used for filtering, selection of fields, grouping and ordering of the fallout exception list. For further details refer to the REST API Reference for Oracle Communications Order and Service Management Cloud Native.

Request

GET /falloutException
There's no request body for this operation.

Response

GET FalloutException list

200
 
[
    {
        "id": "942057168",
        "href": "self",
        "creationDate": "2025-02-13T13:38:36Z",
        "message": "error",
        "orderType": "Product",
        "customerName": "Team2@osm.com",
        "productNames": [
            "Digital IDC OSM"
        ],
        "fullfillmentFunction": "TmfProvFunctionFunction_TmfProvFunctionProcess",
        "taskName": "ProvisionOrderEntryTask",
        "orderId": 19,
        "externalId": "MultipleFTE0000123889",
        "category": "cat1",
        "orderOverdue": true,
        "affectedLines": "Amazon Prime [add]",
        "requestedCompletionDate": "2025-02-13T13:38:36Z",
        "lastUpdatedDate": "2025-02-13T13:38:37Z",
        "state": "created",
        "attributes": [
            {
                "name": "componentNodeIndex",
                "value": "1739453916707"
            },
            {
                "name": "orderComponentKey",
                "value": "TmfProvFunctionFunction"
            },
            {
                "name": "location",
                "value": "testLocation2"
            },
            {
                "name": "orderHistId",
                "value": "302"
            }
        ],
        "taskStatuses": [
            "next"
        ]
    },
    {
        "id": "1397187211",
        "href": "self",
        "creationDate": "2025-02-13T13:38:36Z",
        "message": "error",
        "orderType": "Product",
        "customerName": "Team2@osm.com",
        "productNames": [
            "Digital IDC OSM"
        ],
        "fullfillmentFunction": "TmfProvFunctionFunction_TmfProvFunctionProcess",
        "taskName": "ProvisionOrderEntryTask",
        "orderId": 19,
        "externalId": "MultipleFTE0000123889",
        "category": "cat1",
        "orderOverdue": true,
        "affectedLines": "Amazon Prime [add]",
        "requestedCompletionDate": "2025-02-13T13:38:36Z",
        "lastUpdatedDate": "2025-02-13T13:38:37Z",
        "state": "created",
        "attributes": [
            {
                "name": "componentNodeIndex",
                "value": "1739453916707"
            },
            {
                "name": "orderComponentKey",
                "value": "TmfProvFunctionFunction"
            },
            {
                "name": "location",
                "value": "testLocation1"
            },
            {
                "name": "orderHistId",
                "value": "302"
            }
        ],
        "taskStatuses": [
            "next"
        ]
    },
    {
        "id": "88621671",
        "href": "self",
        "creationDate": "2025-02-13T13:38:34Z",
        "message": "error",
        "orderType": "Product",
        "customerName": "Team2@osm.com",
        "productNames": [
            "Digital IDC OSM"
        ],
        "fullfillmentFunction": "TmfProvFunctionFunction_TmfProvFunctionProcess",
        "taskName": "ProvisionOrderEntryTask",
        "orderId": 18,
        "externalId": "MultipleFTE0000123889",
        "category": "cat1",
        "orderOverdue": true,
        "affectedLines": "Amazon Prime [add]",
        "requestedCompletionDate": "2025-02-13T13:38:33Z",
        "lastUpdatedDate": "2025-02-13T13:38:34Z",
        "state": "created",
        "attributes": [
            {
                "name": "componentNodeIndex",
                "value": "1739453913919"
            },
            {
                "name": "orderComponentKey",
                "value": "TmfProvFunctionFunction"
            },
            {
                "name": "location",
                "value": "testLocation2"
            },
            {
                "name": "orderHistId",
                "value": "302"
            }
        ],
        "taskStatuses": [
            "next"
        ]
    },
    {
        "id": "1935585748",
        "href": "self",
        "creationDate": "2025-02-13T13:38:34Z",
        "message": "error",
        "orderType": "Product",
        "customerName": "Team2@osm.com",
        "productNames": [
            "Digital IDC OSM"
        ],
        "fullfillmentFunction": "TmfProvFunctionFunction_TmfProvFunctionProcess",
        "taskName": "ProvisionOrderEntryTask",
        "orderId": 18,
        "externalId": "MultipleFTE0000123889",
        "category": "cat1",
        "orderOverdue": true,
        "affectedLines": "Amazon Prime [add]",
        "requestedCompletionDate": "2025-02-13T13:38:33Z",
        "lastUpdatedDate": "2025-02-13T13:38:34Z",
        "state": "created",
        "attributes": [
            {
                "name": "componentNodeIndex",
                "value": "1739453913919"
            },
            {
                "name": "orderComponentKey",
                "value": "TmfProvFunctionFunction"
            },
            {
                "name": "location",
                "value": "testLocation1"
            },
            {
                "name": "orderHistId",
                "value": "302"
            }
        ],
        "taskStatuses": [
            "next"
        ]
    },
    {
        "id": "359453722",
        "href": "self",
        "creationDate": "2025-02-04T12:01:43Z",
        "message": "500",
        "orderType": "Product",
        "customerName": "e2e_individual20200428233218579@cheers.com",
        "productNames": [
            "Promotional Offering PS"
        ],
        "fullfillmentFunction": "ProductProvisionOrderFunction_ProductProvisionOrderSubProcess",
        "taskName": "ProductProvisionSITask",
        "orderId": 2,
        "externalId": "456855",
        "category": "category",
        "orderOverdue": true,
        "affectedLines": "Amazon Prime [add]",
        "requestedCompletionDate": "2025-02-04T12:01:40Z",
        "lastUpdatedDate": "2025-02-04T12:03:49Z",
        "recentAction": "cancel",
        "state": "completed",
        "attributes": [
            {
                "name": "componentNodeIndex",
                "value": "1738670500916"
            },
            {
                "name": "orderComponentKey",
                "value": "ProductProvisionOrderFunction.AmazonPrime.WholeGranularity"
            },
            {
                "name": "actionId",
                "value": "1381339654"
            },
            {
                "name": "location",
                "value": "ProductProvisioningComponent"
            },
            {
                "name": "orderHistId",
                "value": "1116"
            }
        ],
        "taskStatuses": [
            "success"
        ]
    },
    {
        "id": "1354901350",
        "href": "self",
        "creationDate": "2025-02-04T12:01:43Z",
        "message": "403: Forbidden",
        "orderType": "Product",
        "customerName": "e2e_individual20200428233218579@cheers.com",
        "productNames": [
            "Promotional Offering PS"
        ],
        "fullfillmentFunction": "Emulated_SOM_Emulator_ProvisionOrder",
        "taskName": "ProvisionOrderEmulatorTask",
        "orderId": 2,
        "externalId": "456855",
        "category": "UnexpectedDownstreamError",
        "orderOverdue": true,
        "affectedLines": "La League VR [add], Text Roaming [add], Data Roaming [add], Wireless Voice Service [add], Voice Roaming [add], SIM Card [add], Wireless Data Service [add], Wireless Text Service [add]",
        "requestedCompletionDate": "2025-02-04T12:01:40Z",
        "lastUpdatedDate": "2025-02-04T12:03:49Z",
        "recentAction": "cancel",
        "state": "completed",
        "attributes": [
            {
                "name": "componentNodeIndex",
                "value": "1738670500914"
            },
            {
                "name": "orderComponentKey",
                "value": "ProvisionOrderFunction.Emulated_SOM.WholeGranularity"
            },
            {
                "name": "actionId",
                "value": "447045169"
            },
            {
                "name": "location",
                "value": "ProvisioningComponent"
            },
            {
                "name": "orderHistId",
                "value": "1114"
            }
        ],
        "taskStatuses": [
            "success"
        ]
    },
    {
        "id": "1778200595",
        "href": "self",
        "creationDate": "2025-02-04T12:01:42Z",
        "message": "500",
        "orderType": "Product",
        "customerName": "e2e_individual20200428233218579@cheers.com",
        "productNames": [
            "Promotional Offering PS"
        ],
        "fullfillmentFunction": "ProductProvisionOrderFunction_ProductProvisionOrderSubProcess",
        "taskName": "ProductProvisionSITask",
        "orderId": 2,
        "externalId": "456855",
        "category": "category",
        "orderOverdue": true,
        "affectedLines": "Disney+ [add]",
        "requestedCompletionDate": "2025-02-04T12:01:40Z",
        "lastUpdatedDate": "2025-02-04T12:04:01Z",
        "recentAction": "cancel",
        "state": "completed",
        "attributes": [
            {
                "name": "componentNodeIndex",
                "value": "1738670500917"
            },
            {
                "name": "orderComponentKey",
                "value": "ProductProvisionOrderFunction.Disney.WholeGranularity"
            },
            {
                "name": "actionId",
                "value": "458412405"
            },
            {
                "name": "location",
                "value": "ProductProvisioningComponent"
            },
            {
                "name": "orderHistId",
                "value": "1117"
            }
        ],
        "taskStatuses": [
            "success"
        ]
    }
]

The following table shows the API attributes and example values for retrieving the Fallout Exception details by ID:

Table 5-5 API Attributes for Retrieving Fallout Exception Details by ID

API Attribute	Value
API Endpoint URL	`http://hostname:port/orchestration/sr/quick/falllout/v2.0/falloutException/{falloutExceptionId}` where `hostname` and `port` are the access details of the Kubernetes cluster exposed by your Ingress Controller or Load Balancer.
Request Type	GET.
Request Header	There are no request headers for this operation.
Request Body	There's no request body for this operation.
Authentication	`Authorization:Bearer access-token` (The key-value added as header).
Query Parameters	Query parameters are used for selecting fields in the response. For further details refer to the REST API Reference for Oracle Communications Order and Service Management Cloud Native.
Path Parameter	falloutExceptionId: Identifier of the Fallout Exception.

Request

GET /falloutException/1791523756
There's no request body for this operation.

Response

Get Fallout Exception By ID Response

200
 
[
    {
        "id": "1791523756",
        "href": "self",
        "creationDate": "2025-02-13T13:38:48Z",
        "message": "error",
        "orderType": "Product",
        "customerName": "Team2@osm.com",
        "productNames": [
            "Digital IDC OSM"
        ],
        "fullfillmentFunction": "TmfProvFunctionFunction_TmfProvFunctionProcess",
        "taskName": "ProvisionOrderEntryTask",
        "orderId": 22,
        "externalId": "0000123889",
        "category": "cat1",
        "orderOverdue": true,
        "affectedLines": "Amazon Prime [add]",
        "requestedCompletionDate": "2025-02-13T13:38:47Z",
        "lastUpdatedDate": "2025-02-13T13:38:48Z",
        "state": "created",
        "attributes": [
            {
                "name": "componentNodeIndex",
                "value": "1739453927876"
            },
            {
                "name": "orderComponentKey",
                "value": "TmfProvFunctionFunction"
            },
            {
                "name": "location",
                "value": "testLocation"
            },
            {
                "name": "orderHistId",
                "value": "302"
            }
        ],
        "taskStatuses": [
            "next"
        ]
    }
]

POST Endpoints

The following table shows the API attributes and sample values for a task level submitFalloutAction request (retry and force complete task):

Table 5-6 API Attributes for a Task Level submitFalloutAction Request

API Attribute	Value
API Endpoint URL	`http://hostname:port/orchestration/sr/quick/falllout/v2.0/falloutException/{falloutExceptionId}/submitFalloutAction` where `hostname` and `port`are the access details of the Kubernetes cluster exposed by your Ingress Controller or Load Balancer.
Request Type	POST.
Request Header	`Content-Type:application/json` (The key-value is added as a header).
Request Body	JSON payload of action schema.
Authentication	`Authorization:Bearer access-token` (The key-value is added as a header).
Path Parameter	`falloutExceptionId`: Identifier of the fallout exception.

Request

POST /falloutException/{falloutExceptionId}/submitFalloutException
Content-Type: application/json

Force Complete Task

The request JSON payload needed to provide the taskStatus for marking the task complete. The task status information is made available by the GET falloutException API response body attribute taskStatuses. The task status is optional when the number of the taskStatuses is 1.

action_forceCompleteAction Schema Sample

{
  "falloutAction": "forceComplete",
  "taskStatus": "next", 
  "author": "fallout user"
}

Retry Task

action_otherFalloutAction Schema Sample

{
  "falloutAction": "retry",
  "author": "fallout user"
}

Response

The following table shows the API attributes and sample values for an order level submitFalloutAction request (failOrder, cancelOrder, abortOrder).

Table 5-7 API Attributes and Sample Values for an Order Level submitFalloutAction Request

API Attribute	Value
API Endpoint URL	`http://hostname:port/orchestration/sr/quick/falllout/v2.0/falloutException/submitFalloutAction` where `hostname` and `port`are the access details of the Kubernetes cluster exposed by your Ingress Controller or Load Balancer.
Request Type	POST.
Request Header	`Content-Type:application/json` (The key-value is added as a header).
Request Body	JSON payload of actionOnOrder SchemaOrderId for which the fallout action is submitted is part of the request body. For further details refer to the REST API Reference for Oracle Communications Order and Service Management Cloud Native.
Authentication	`Authorization:Bearer access-token` (The key-value is added as a header.)

For details about the Constructing the HTTP request for client, refer to Using TMF REST APIs (Cloud Native Only).

Request

POST /falloutException/submitFalloutException 
Content-Type: application/json

Cancel Order

actionOnOrder Schema Sample

{
  "falloutAction": "cancel",
  "id": 11,
  "author": "fallout user"
}

Abort Order

actionOnOrder Schema Sample

{
  "falloutAction": "abort",
  "id": 11,
  "author": "fallout user"
}

Fail Order

actionOnOrder Schema Sample

{
  "falloutAction": "failOrder",
  "id": 11,
  "author": "fallout user"
}

Response

5 Fallout Exception Management Rest APIs V2.0 (Cloud Native Only)

Fallout Exception Management Rest API Versions

Fallout Exception Lifecycle

Support for Filtering, Grouping and Ordering of Fallout Exception Objects

Filtering and Attribute Selection Rules

Grouping

Ordering

Additional Query Fields

Supported Fallout Actions

API Operations

Authentication and Authorization

Constructing the Endpoint

GET Endpoints

POST Endpoints