REST API for Oracle Fusion Cloud SCM

You can use REST API to create a recommendation for diagnosing and repairing a failed asset or for optimizing a maintenance program. A recommendation could be related to an asset failure or a maintenance program. Recommendations can come from machine-learning tools like the Oracle Fusion Cloud IoT Asset Monitoring Service, Oracle Machine Learning, Oracle Analytics Cloud, Python, or TensorFlow. Recommendations can also come from direct input from a planner, manager, or support specialist.

Here's a typical application processing flow for the scenarios:

You create a recommendation that predicts the most likely cause of asset failure.
You create a recommendation that predicts how best to resolve an asset failure.
You create a recommendation that predicts the most likely component part that caused an asset to fail.
You create a recommendation for optimizing a calendar-based maintenance interval.
You create a recommendation for optimizing a meter-based maintenance interval.
You may choose to accept or reject a recommendation.

Create a Recommendation Predicting Most Likely Cause of Failure

In this scenario, you create a recommendation predicting the most likely cause of failure for an asset. This type of scenario might provide guidance to a planner or technician on how to diagnose and troubleshoot a failed asset. Ideally, multiple recommendations along with their relative confidence levels would be presented for the user to assess and choose from.

Example URL

Use this resource URL format.

POST

curl -u username:password -X POST -H "Content-Type:application/vnd.oracle.adf.resourceitem+json" -d 'request payload' "https://servername/fscmRestApi/resources/latest/maintenanceRecommendations"

Example Request

This table shows the typical attributes to create a recommendation:

Table -

Value	Description
RecObject	A string lookup that indicates the target object for a recommendation. This can be either an asset failure instance (ORA_ASSET_FAILURE) or a maintenance program work requirement (ORA_WORK_REQUIREMENT). This value is mandatory.
RecObjectId	System-generated unique identifier for the RecObject. If RecObject is ORA_ASSET_FAILURE, then the RecObjectId is a FailureInstanceId for the related asset failure instance. If RecObject is ORA_ WORK_REQUIREMENT, then the RecObjectId is a WorkRequirementId for the related maintenance program work requirement. This value is mandatory.
RecEntityAttrOne	A string lookup that indicates the attribute to which the recommendation applies. This value can be: ORA_CAUSE_CODE ORA_RESOLUTION_CODE ORA_FAILED_COMPONENT ORA_CALENDAR_INTERVAL ORA_METER_INTERVAL This value is mandatory.
RecEntityAttrOneValue	System-generated unique identifier for MeterDefinitionId. This is needed specifically for meter intervals because a work requirement can have more than one meter interval but only one calendar interval. This value is mandatory only when RecEntityAttrOne is ORA_METER_INTERVAL.
Current Value	Free-text string indicating the current maintenance interval for the maintenance program work requirement specified by the RecObjectId. When RecEntityAttrOne is ORA_CALENDAR_INTERVAL, it expresses the days in the maintenance interval, and when RecEntityAttrOne is ORA_METER_INTERVAL, it expresses the meter units in the interval. This value is null for asset failure recommendations. This value is not mandatory.
RecommendedValue	Numeric value indicating the recommended or predicted value for the target attribute. When RecEntityAttrOne is ORA_CALENDAR_INTERVAL, this value is the days in the recommended maintenance interval. When RecEntityAttrOne is ORA_METER_INTERVAL, this value is the meter units in the recommended maintenance interval. When RecEntityAttrOne is ORA_CAUSE_CODE, this value is the ConditionEventCodeId of the predicted Cause Code. When RecEntityAttrOne is ORA_RESOLUTION_CODE, this value is the ConditionEventCodeId of the recommended Resolution Code. When RecEntityAttrOne is ORA_FAILED_COMPONENT, this value is the FailedComponentItemId (that is, Inventory Item ID) of the predicted failed component. This value is mandatory.
ConfidenceLevel	A percentage between 0 and 100 that represents the likelihood that the recommendation or prediction is correct or will satisfy the user's request. A confidence score is generally provided by a machine-learning prediction. This value is not mandatory.
Insight	A free-text description of the reasons why a prediction or recommendation was made so that the user has the appropriate context to make a decision to accept or reject the recommendation. For example, for a decision-tree algorithm, the splitting rules at each traversed node of the tree could be provided.
SourceRecId	A free-text description of where the recommendation came from. For example, IoT Asset Monitoring Service or Python Optimization Program.
LearningWorkflowId	A free-text field to capture the system-generated unique identifier of the workflow used for generating a recommendation.
LearningThreadId	A free-text field to capture the system-generated unique identifier of the learning thread used for generating a recommendation.

Here's an example of the request body in JSON format.

{
    "RecObject": "ORA_ASSET_FAILURE", 
    "RecObjectId": 300100552615492,
    "RecEntityAttrOne": "ORA_CAUSE_CODE",
    "RecommendedValue": 300100556909113,  
    "ConfidenceLevel": 91,
    "Insight": "Most likely cause for the given item, item age, failure code and symptoms."
}

Example Response

Here's an example of the response body in JSON format.

{
    "RecId": 300100556949819,
    "SourceRecId": null,
    "RecObjectId": 300100552615492,
    "RecObject": "ORA_ASSET_FAILURE",
    "RecEntityAttrOne": "ORA_CAUSE_CODE",
    "RecEntityAttrOneValue": null,
    "RecEntityAttrTwo": null,
    "RecEntityAttrTwoValue": null,
    "RecEntityAttrThree": null,
    "RecEntityAttrThreeValue": null,
    "RecommendedValue": 300100556909113,
    "CurrentValue": null,
    "Insight": "Most likely cause for the given item, item age, failure code and symptoms.",
    "InsightObjectId": null,
    "LearningThreadId": null,
    "LearningWorkflowId": null,
    "InsightObjectTypeCode": null,
    "ConfidenceLevel": 91,
    "ActionCode": null,
    "CreatedBy": "MNT_QA",
    "CreationDate": "2022-01-19T14:04:24+00:00",
    "LastUpdateDate": "2022-01-19T14:04:24.081+00:00",
    "LastUpdateLogin": "D5C58CBD141230A9E053D45AF00ABD59",
    "LastUpdatedBy": "MNT_QA",
    "links": [
        {
            "rel": "self",
            "href": "https://servername/fscmRestApi/resources/version/maintenanceRecommendations/300100556949819",
            "name": "maintenanceRecommendations",
            "kind": "item",
            "properties": {
                "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
            }
        },
        {
            "rel": "canonical",
            "href": "https://servername/fscmRestApi/resources/version/maintenanceRecommendations/300100556949819",
            "name": "maintenanceRecommendations",
            "kind": "item"
        }
    ]
}

Create a Recommendation Predicting the Best Resolution for a Failure

In this scenario, you create a recommendation predicting the most likely best resolution for fixing an asset failure. This type of scenario might provide guidance to a planner or technician on how best to fix a failed asset. Ideally, multiple recommendations along with their relative confidence levels would be presented for the user to assess and choose from.

Example URL

Use this resource URL format.

POST

curl -u username:password -X POST -H "Content-Type:application/vnd.oracle.adf.resourceitem+json" -d 'request payload' "https://servername/fscmRestApi/resources/latest/maintenanceRecommendations"

Example Request

Here's an example of the request body in JSON format.

{
    "RecObject": "ORA_ASSET_FAILURE", 
    "RecObjectId": 300100552615492,
    "RecEntityAttrOne": "ORA_RESOLUTION_CODE",
    "RecommendedValue": 300100556909277,  
    "ConfidenceLevel": 80,
    "Insight": "Most likely best fix for the given item, item age, failure code and symptoms."
}

Example Response

Here's an example of the response body in JSON format.

{
    "RecId": 300100556964509,
    "SourceRecId": null,
    "RecObjectId": 300100552615492,
    "RecObject": "ORA_ASSET_FAILURE",
    "RecEntityAttrOne": "ORA_RESOLUTION_CODE",
    "RecEntityAttrOneValue": null,
    "RecEntityAttrTwo": null,
    "RecEntityAttrTwoValue": null,
    "RecEntityAttrThree": null,
    "RecEntityAttrThreeValue": null,
    "RecommendedValue": 300100556909277,
    "CurrentValue": null,
    "Insight": "Most likely best fix for the given item, item age, failure code and symptoms.",
    "InsightObjectId": null,
    "LearningThreadId": null,
    "LearningWorkflowId": null,
    "InsightObjectTypeCode": null,
    "ConfidenceLevel": 80,
    "ActionCode": null,
    "CreatedBy": "MNT_QA",
    "CreationDate": "2022-01-19T15:06:44+00:00",
    "LastUpdateDate": "2022-01-19T15:06:44.078+00:00",
    "LastUpdateLogin": "D5C58CBD16D530A9E053D45AF00ABD59",
    "LastUpdatedBy": "MNT_QA",
    "links": [
        {
            "rel": "self",
            "href": "https://servername/fscmRestApi/resources/version/maintenanceRecommendations/300100556964509",
            "name": "maintenanceRecommendations",
            "kind": "item",
            "properties": {
                "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
            }
        },
        {
            "rel": "canonical",
            "href": "https://servername/fscmRestApi/resources/version/maintenanceRecommendations/300100556964509",
            "name": "maintenanceRecommendations",
            "kind": "item"
        }
    ]
}

Create a Recommendation Predicting the Most Likely Failed Component

In this scenario, you create a recommendation predicting the most likely component to have failed when an asset fails. This type of scenario might provide guidance to a planner or technician on how best to fix a failed asset and which parts are needed. Ideally, multiple recommendations along with their relative confidence levels would be presented for the user to assess and choose from.

Example URL

Use this resource URL format.

POST

curl -u username:password -X POST -H "Content-Type:application/vnd.oracle.adf.resourceitem+json" -d 'request payload' "https://servername/fscmRestApi/resources/latest/maintenanceRecommendations"

Example Request

Here's an example of the request body in JSON format.

{
    "RecObject": "ORA_ASSET_FAILURE", 
    "RecObjectId": 300100552615492,
    "RecEntityAttrOne": "ORA_FAILED_COMPONENT",
    "RecommendedValue": 300100114215977,  
    "ConfidenceLevel": 85,
    "Insight": "Most likely component to fail for the given item, item age, failure code and symptoms."
}

Example Response

Here's an example of the response body in JSON format.

{
    "RecId": 300100548919555,
    "SourceRecId": null,
    "RecObjectId": 300100552615492,
    "RecObject": "ORA_ASSET_FAILURE",
    "RecEntityAttrOne": "ORA_FAILED_COMPONENT",
    "RecEntityAttrOneValue": null,
    "RecEntityAttrTwo": null,
    "RecEntityAttrTwoValue": null,
    "RecEntityAttrThree": null,
    "RecEntityAttrThreeValue": null,
    "RecommendedValue": 300100114215977,
    "CurrentValue": null,
    "Insight": "Most likely component to fail for the given item, item age, failure code and symptoms.",
    "InsightObjectId": null,
    "LearningThreadId": null,
    "LearningWorkflowId": null,
    "InsightObjectTypeCode": null,
    "ConfidenceLevel": 85,
    "links": [
        {
            "rel": "self",
            "href": "https://servername/fscmRestApi/resources/version/maintenanceRecommendations/300100548919555",
            "name": "maintenanceRecommendations",
            "kind": "item",
            "properties": {
                "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
            }
        },
        {
            "rel": "canonical",
            "href": "https://servername/fscmRestApi/resources/version/maintenanceRecommendations/300100548919555",
            "name": "maintenanceRecommendations",
            "kind": "item"
        }
    ]
}

Create a Recommendation for Optimizing a Calendar-Based Maintenance Interval

In this scenario, you create a recommendation for optimizing a calendar-based maintenance interval. This type of scenario might provide guidance to a planner on how best to schedule regular part replacements to ensure assets maintain a specified target level of reliability. Based on historical failure data, an optimal maintenance program would ensure parts are replaced before they are likely to fail, but not too soon before the part reaches its reliable lifespan.

Example URL

Use this resource URL format.

POST

curl -u username:password -X POST -H "Content-Type:application/vnd.oracle.adf.resourceitem+json" -d 'request payload' "https://servername/fscmRestApi/resources/latest/maintenanceRecommendations"

Example Request

Here's an example of the request body in JSON format.

{
    "SourceRecId": "IoT",
    "RecObject": "ORA_WORK_REQUIREMENT",
    "RecObjectId": 300100178577541,
    "RecEntityAttrOne": "ORA_CALENDAR_INTERVAL",
    "ConfidenceLevel": 90,
    "RecommendedValue": 92,
    "CurrentValue": 30,
    "Insight": "Oil Filter replaced with more than 60% useful lifespan remaining."
}

Example Response

Here's an example of the response body in JSON format.

{
    "RecId": 300100548919557,
    "SourceRecId": "IoT",
    "RecObjectId": 300100178577541,
    "RecObject": "ORA_WORK_REQUIREMENT",
    "RecEntityAttrOne": "ORA_CALENDAR_INTERVAL",
    "RecEntityAttrOneValue": null,
    "RecEntityAttrTwo": null,
    "RecEntityAttrTwoValue": null,
    "RecEntityAttrThree": null,
    "RecEntityAttrThreeValue": null,
    "RecommendedValue": 92,
    "CurrentValue": 30,
    "Insight": "Oil Filter replaced with more than 60% useful lifespan remaining.",
    "InsightObjectId": null,
    "LearningThreadId": null,
    "LearningWorkflowId": null,
    "InsightObjectTypeCode": null,
    "ConfidenceLevel": 90,
    "links": [
        {
            "rel": "self",
            "href": "https://servername/fscmRestApi/resources/version/maintenanceRecommendations/300100548919557",
            "name": "maintenanceRecommendations",
            "kind": "item",
            "properties": {
                "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
            }
        },
        {
            "rel": "canonical",
            "href": "https://servername/fscmRestApi/resources/version/maintenanceRecommendations/300100548919557",
            "name": "maintenanceRecommendations",
            "kind": "item"
        }
    ]
}

Create a Recommendation for Optimizing a Meter-Based Maintenance Interval

In this scenario, you create a recommendation for optimizing a meter-based maintenance interval. This type of scenario might provide guidance to a planner on how best to schedule regular part replacements to ensure assets maintain a specified target level of reliability. Based on historical failure data, an optimal maintenance program would ensure parts are replaced before they are likely to fail, but not too soon before the part reaches its reliable lifespan.

Example URL

Use this resource URL format.

POST

curl -u username:password -X POST -H "Content-Type:application/vnd.oracle.adf.resourceitem+json" -d 'request payload' "https://servername/fscmRestApi/resources/latest/maintenanceRecommendations"

Example Request

Here's an example of the request body in JSON format.

{
    "SourceRecId": "IoT",
    "RecObject": "ORA_WORK_REQUIREMENT",
    "RecObjectId": 300100171239901,
    "RecEntityAttrOne": "ORA_METER_INTERVAL",
    "RecEntityAttrOneValue": 300100171239889,
    "ConfidenceLevel": 82,
    "RecommendedValue": 30000,
    "CurrentValue": 50000,
    "Insight": "Oil Filter has a 33% chance of failing before reaching replacement interval. Target reliability rate will not be met with this maintenance interval."
}

Example Response

Here's an example of the response body in JSON format.

{
    "RecId": 300100548919561,
    "SourceRecId": "IoT",
    "RecObjectId": 300100171239901,
    "RecObject": "ORA_WORK_REQUIREMENT",
    "RecEntityAttrOne": "ORA_METER_INTERVAL",
    "RecEntityAttrOneValue": 300100171239889,
    "RecEntityAttrTwo": null,
    "RecEntityAttrTwoValue": null,
    "RecEntityAttrThree": null,
    "RecEntityAttrThreeValue": null,
    "RecommendedValue": 30000,
    "CurrentValue": 50000,
    "Insight": "Oil Filter has a 33% chance of failing before reaching replacement interval. Target reliability rate will not be met with this maintenance interval.",
    "InsightObjectId": null,
    "LearningThreadId": null,
    "LearningWorkflowId": null,
    "InsightObjectTypeCode": null,
    "ConfidenceLevel": 82,
    "links": [
        {
            "rel": "self",
            "href": "https://servername/fscmRestApi/resources/version/maintenanceRecommendations/300100548919561",
            "name": "maintenanceRecommendations",
            "kind": "item",
            "properties": {
                "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
            }
        },
        {
            "rel": "canonical",
            "href": "https://servername/fscmRestApi/resources/version/maintenanceRecommendations/300100548919561",
            "name": "maintenanceRecommendations",
            "kind": "item"
        }
    ]
}

Accept or Reject a Recommendation

In this scenario, you update an existing recommendation to indicate whether to accept or reject the recommendation. A historical record is stored with information about which recommendations were accepted and rejected, by whom, and the reasons for the decision. This can be used to make better recommendations in the future.

Example URL

Use this resource URL format.

PATCH

curl -u username:password -X PATCH -H "Content-Type:application/vnd.oracle.adf.resourceitem+json" -d 'request payload' "https://servername/fscmRestApi/resources/latest/maintenanceRecommendations/RecId"

This table shows the typical attributes to accept or reject a recommendation.

Table -

Value	Description
ActionCode	String lookup that indicates whether to accept (ORA_ACCEPT), reject (ORA_REJECT), or override (ORA_OVERRIDE) the recommendation. Note that overriding a recommendation is effectively the same as rejecting it, but with the addition of providing a specific value (NewValue) to which the recommendation should be changed.
Reason	Business-defined extensible lookup code describing the reason the user chose to accept, reject, or override a recommendation.
Comments	Free-text comments provided by a user with additional information regarding why they chose to accept, reject, or override a recommendation.
NewValue	Numeric value indicating the value to which a user wishes to change the recommended or predicted value for the target attribute. This value is only relevant when the user chooses the ActionCode ORA_OVERRIDE.

Example Request

Here's an example of the request body in JSON format.

{
    "ActionCode": "ORA_ACCEPT"
}

Example Response

Here's an example of the response body in JSON format.

{
    "RecId": 300100556949819,
    "SourceRecId": null,
    "RecObjectId": 300100552615492,
    "RecObject": "ORA_ASSET_FAILURE",
    "RecEntityAttrOne": "ORA_CAUSE_CODE",
    "RecEntityAttrOneValue": null,
    "RecEntityAttrTwo": null,
    "RecEntityAttrTwoValue": null,
    "RecEntityAttrThree": null,
    "RecEntityAttrThreeValue": null,
    "RecommendedValue": 300100556909113,
    "CurrentValue": null,
    "Insight": "Most likely cause for the given item, item age, failure code and symptoms.",
    "InsightObjectId": null,
    "LearningThreadId": null,
    "LearningWorkflowId": null,
    "InsightObjectTypeCode": null,
    "ConfidenceLevel": 0,
    "ActionCode": "ORA_ACCEPT",
    "CreatedBy": "MNT_QA",
    "CreationDate": "2022-01-19T14:04:24+00:00",
    "LastUpdateDate": "2022-01-19T15:46:47+00:00",
    "LastUpdateLogin": "D5C58CB130A630ADE053D45AF00A3CF9",
    "LastUpdatedBy": "MNT_QA",
    "links": [
        {
            "rel": "self",
            "href": "https://servername/fscmRestApi/resources/version/maintenanceRecommendations/300100556949819",
            "name": "maintenanceRecommendations",
            "kind": "item",
            "properties": {
                "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000278"
            }
        },
        {
            "rel": "canonical",
            "href": "https://servername/fscmRestApi/resources/version/maintenanceRecommendations/300100556949819",
            "name": "maintenanceRecommendations",
            "kind": "item"
        }
    ]
}