X

Best Practices from Oracle Development's A‑Team

Using the Oracle SCM Cloud R12 REST API

Stefan Koser
Consulting Solutions Architect

Overview

Update August 2019: Please note that this blog was written in 2017 when SCM Cloud R13 was available. The Current version is R13 19B. Although much of this blog still applies, some steps may be different meanwhile. Please visit https://docs.oracle.com/en/cloud/saas/supply-chain-management/19b/index.html  for the latest.

Starting with Release 12, Oracle SCM Cloud provides a REST API - which is easier to use in a lot of cases than the SOAP API and also offers some additional capabilities like the access to the WorkOrder service. Also it can be very easily used by the Oracle IoT Cloud Service and Oracle Integration Cloud Service to integrate with SCM Cloud. (I will show the integration with ICS in a later post)

As an example how to use the REST API, we will look at this simplified scenario (which is part of the VISION demo instance):

Sample_SCM_Process

The requirements for an API in this example are

  • Update Work Orders from Status "Released" to Status "On Hold" (for example in case the work order operation "Testing" failed)

  • Update Work Order Operations, so that one operation gets completed, and the next operation starts

Part 1: Read and Update a Work Order Status

First we will create a new work order and release it from the Fusion SCM UI:

released_work_order

The first REST call shows how to get the work order status.  The REST resource "workOrders" by default takes the work order id instead of the number, so we need to pass the number as query parameter (filter):

URL:

https://<scm host>/manufacturingApi/resources/latest/
workOrders?q=WorkOrderNumber=WO-002-1012

Http Method:

GET

Authentication:

Basic  (I have used SCM_IMPL user)

I have used Postman, a plugin for Chrome but you can use any other REST client. You can find the sample REST JSON response here.

The second call shows how to programmatically modify the work order from status "Released" to status "On hold".

The Fusion SCM API (as other REST APIs) uses the http operations in the following ways

  • GET: Retrieve (query) an object of all objects

  • PATCH: Update an object

  • POST: Create an object

Before we can construct a REST call, we need to look up the work order status codes:

Status Codes

  • 10000: Cancelled

  • 10001: Closed

  • 10002: Completed

  • 10003: On hold

  • 10004: Released

  • 10005: Unreleased

The REST call to update the work order status looks like this: (in this case we use the work order id as template parameter)

URL:

https://<scm host>/manufacturingApi/resources/latest/
workOrders/300000141829792

Http Method:

PATCH

Authentication:

Basic

Header:

Content-Type: application/vnd.oracle.adf.resourceitem+json

Body:
{
"WorkOrderId" : 300000141829792,
"WorkOrderNumber" : "WO-002-1012",
"WorkOrderStatusId" : 10003
}

It is important to use the correct Content Type "application/vnd.oracle.adf.resourceitem+json".  If you try only with "application/json", you will get the http error "415 - unsupported media type" with the additional description "The content type is not a ADFm REST entity."

The response will be a simple http 200 (ok) return code. You can verify on the SCM UI that the Work Order is now in status "On hold":work_order_changed_to_on_hold

Part 2: Read and Update Work Order Operations

In our sample scenario, the Word Order is executed by three Work Order Operations:

10 - Tablet Assembly
20 - Tablet Testing
30 - Tablet Packaging

After changing back the work order to status "Released", we can modify the Work Order Operations. In the initial released state, the first work order operation is in state "Ready". This is how it looks on the SCM UI:

workorder_operations_ready

The first REST call is to get all Work Order Operations and their status:

URL:

https://<scm host>/manufacturingApi/resources/latest/workOrders/
300000141829792/child/WorkOrderOperation

Http Method:

GET

Authentication:

Basic

 

The result looks like this:

{
"items": [
{
"OrganizationId": 300000047274447,
"WorkOrderId": 300000141829792,
"WorkOrderNumber": "WO-002-1012",
"WorkOrderOperationId": 300000141829793,
"OperationSequenceNumber": 10,
"OperationName": "Tablet Assembly",
…
"ReadyQuantity": 1,
"CompletedQuantity": null,
"ActualStartDate": null,
"ActualCompletionDate": null,
…
},
{
"OrganizationId": 300000047274447,
"WorkOrderId": 300000141829792,
"WorkOrderNumber": "WO-002-1012",
"WorkOrderOperationId": 300000141829794,
"OperationSequenceNumber": 20,
"OperationName": "Tablet Testing",
…
"ReadyQuantity": null,
"CompletedQuantity": null,
…
"ActualStartDate": null,
"ActualCompletionDate": null,
…
},
{
"OrganizationId": 300000047274447,
"WorkOrderId": 300000141829792,
"WorkOrderNumber": "WO-002-1012",
"WorkOrderOperationId": 300000141829795,
"OperationSequenceNumber": 30,
"OperationName": "Tablet Packing",
…
"ReadyQuantity": null,
"CompletedQuantity": null,
…
"ActualStartDate": null,
"ActualCompletionDate": null,
…

Every WorkOrderOperation has a ReadyQuantity and a CompletedQuantity.

Now we can complete the first Work Order Operation "10" by setting the CompletedQuantity to 1 via the REST API.

We first try this using a PATCH REST call to the same resource - as it would be the intuitive way with REST:

URL:

https://<scm host>/manufacturingApi/resources/latest/
workOrders/300000141829792/child/WorkOrderOperation/300000141829793

Http Method:

PATCH

Authentication:

Basic

Header:

Content-Type: application/vnd.oracle.adf.resourceitem+json

Body:

{
   "CompletedQuantity": 1
}

 

This "surprisingly" results in an error response: http 400 “Bad Request”  - detail: The action is not enabled. Action name: "update".

The reason is that SCM Cloud has a different operation to start a transaction on a work order operation. The API you need to use instead is https://docs.oracle.com/cloud/latest/scmcs_gs/FASRP/op-manufacturingApi-resources-11.12.1.0-operationTransactions-post.html

Therefore we create a new Work Order Operation Transaction with this REST call using the POST method to transfer items from state "Ready" to "Complete":

URL:

https://<scm host>//manufacturingApi/resources/latest/operationTransactions

Http Method:

POST

Authentication:

Basic

Header:

Content-Type: application/vnd.oracle.adf.resourceitem+json

Body:

{
  "SourceSystemCode" : "FUSION_MOBILE",
  "SourceSystemType" : "EXTERNAL",
  "OperationTransactionDetail" : [ {
     "SourceSystemCode" : "FUSION_MOBILE",
     "OrganizationCode" : "002",
     "TransactionDate" : "2017-05-29T15:12:30",
     "TransactionQuantity" : 1,
     "TransactionUnitOfMeasure" : "Ea",
     "WoOperationSequenceNumber" : 10,
     "WorkOrderNumber" : "WO-002-1012",
     "FromDispatchState" : "READY",
     "ToDispatchState" : "COMPLETE"
  } ]
}

 

Be careful: even if the http response code is 201 (Created) as expected - there can also be errors reported in the JSON response payload (which actual indicate that the request failed).

An error happens for example if the TransactionDate is wrong. The response JSON payload in this case may contain this reason:

"ErrorMessages": "The value of Transaction Date attribute 2017-05-30 00:12:30.000000 is invalid. Transaction Date must be between work order release date and current date."

The correct response without errors looks like this: workorderoperationtransaction_create_response. We can verify this by the SCM UI, where you will notice the first operation (10) changed to "Completed: 1", the second (20) automatically completed (as setup in the definition), and now the third operation (30) in state "Ready".

workorderoperationtransaction_create_response

Once we send a REST call to create another Work Order Operation Transaction to complete last operation "30", then the whole Work Order will be marked as "Completed". See the following 2 screen shots:

workorderoperationtransaction_all_completed

workorder_completed

This concludes the first post on how to use the Fusion SCM Cloud REST API. We have used all 3 types of REST operations, GET, PATCH and POST, - and showed how to retrieve and update objects in Oracle Fusion SCM Cloud R12 via REST.

Further References

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha