> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-2/guides/system-connectivity/mes-erp-business-systems/oracle-fusion-cloud-scm-integration.md).

# Oracle Fusion Cloud SCM Integration

This guide describes how to integrate Oracle Fusion Cloud Supply Chain Management (SCM) with Connectware. You configure a service commissioning file that reports production progress from the shop floor to Oracle Manufacturing through its REST APIs and polls work orders in return. A complete example file is available at the end of this guide.

## Objectives

* Establishing a connection between Connectware and the Oracle Fusion Cloud SCM REST APIs.
* Reporting work order operation transactions with shop floor data.
* Reporting material transactions for component issues and returns.
* Polling released work orders and publishing them to the MQTT topic hierarchy.

## Prerequisites

To follow this guide, you will need the following:

* A running instance of Cybus Connectware.
* Access to an Oracle Fusion Cloud SCM environment with the Manufacturing offering, and the hostname of your instance. For example, `servername.fa.us2.oraclecloud.com`.
* A dedicated integration user with the privileges to view work orders and report production transactions in the target manufacturing organization.
* Manufacturing master data in Oracle Fusion Cloud: an organization code and at least one released work order with operations.
* Access to the [Admin UI](/2-4-2/access/admin-ui.md) with sufficient [user permissions](/2-4-2/access/user-management.md).
* Basic knowledge of MQTT and the Connectware [services](/2-4-2/data-flows/services.md) concept (for example, [service commissioning files](/2-4-2/data-flows/service-commissioning-files.md), [connections](/2-4-2/data-flows/service-commissioning-files/resources/cybus-connection.md), and [endpoints](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md)).

## Connectware and Oracle Fusion Cloud SCM Integration

Oracle Fusion Cloud SCM exposes its functionality as REST APIs under a common base path of the form `https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05`. The version segment `11.13.18.05` is the stable REST API version of Oracle Fusion Cloud Applications. The APIs support [basic authentication over TLS as well as SAML and JWT tokens](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/26b/fasrp/Quick_Start.html). Connectware communicates with these APIs through the [HTTP/REST connector](/2-4-2/connectors/enterprise-connectors/http-rest.md).

This guide uses three Manufacturing resources of the [REST API for Oracle Fusion Cloud SCM](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/26b/fasrp/index.html):

* [**Operation Transactions**](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/26b/fasrp/op-operationtransactions-post.html) (`/operationTransactions`): Reports the progress of work order operations, such as completed quantities.
* [**Material Transactions**](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/26b/fasrp/op-materialtransactions-post.html) (`/materialTransactions`): Reports components that are issued to or returned from a work order.
* [**Work Orders**](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/26b/fasrp/op-workorders-get.html) (`/workOrders`): Provides the work orders of a manufacturing organization. Connectware polls this resource and publishes the result to an MQTT topic.

The MQTT topics in this guide follow an ISA-95-style equipment hierarchy (`<enterprise>/<site>/<area>/<line>/<cell>`). The mappings subscribe with wildcards across all levels, so any machine in the hierarchy is picked up without changing the integration.

### Oracle Fusion Cloud SCM Connection Properties

The connection to Oracle Fusion Cloud SCM requires the hostname of your instance and the credentials of the integration user. We add them as parameters to the service commissioning file, so you can set them when you install the service.

Do not worry about copying the service commissioning file snippets together into one, the complete example file is available at the end of this guide.

* `oracleFusionHost`: The hostname of your Oracle Fusion Cloud instance, without the scheme. For example, `example.fa.us2.oraclecloud.com`.
* `restApiVersion`: The REST API version in the base path. Defaults to `11.13.18.05`.
* `integrationUsername` and `integrationPassword`: The credentials of the integration user.
* `organizationCode`: The code of the manufacturing organization whose work orders are polled.
* `pollInterval`: The polling interval for work orders in milliseconds. Defaults to one minute.
* `topicRoot`: The root of the MQTT topic hierarchy. Defaults to `enterprise`.

{% code lineNumbers="true" %}

```yaml
parameters:
  oracleFusionHost:
    description: Hostname of your Oracle Fusion Cloud instance
    type: string
    default: example.fa.us2.oraclecloud.com

  restApiVersion:
    description: Version of the Oracle Fusion Cloud REST API
    type: string
    default: 11.13.18.05

  integrationUsername:
    description: Username of the Oracle Fusion Cloud integration user
    type: string

  integrationPassword:
    description: Password of the Oracle Fusion Cloud integration user
    type: string

  organizationCode:
    description: Code of the manufacturing organization to poll work orders for
    type: string
    default: PLANT01

  pollInterval:
    description: Polling interval for work orders in milliseconds
    type: integer
    default: 60000

  topicRoot:
    description: Root of the MQTT topic hierarchy
    type: string
    default: enterprise
```

{% endcode %}

### Oracle Fusion Cloud SCM Connection

To connect to the Oracle Fusion Cloud REST APIs, we set up a `Cybus::Connection` resource that uses the HTTP/REST connector with basic authentication. The `auth` property holds the credentials of the integration user, and the `prefix` property applies the common base path to all endpoints of this connection. This keeps the endpoint paths short and moves the API version into a single parameter.

{% code lineNumbers="true" %}

```yaml
resources:
  oracleFusionConnection:
    type: Cybus::Connection
    properties:
      protocol: Http
      connection:
        scheme: https
        host: !ref oracleFusionHost
        port: 443
        prefix: !sub '/fscmRestApi/resources/${restApiVersion}'
        auth:
          username: !ref integrationUsername
          password: !ref integrationPassword
```

{% endcode %}

If your environment requires additional headers on every request, for example `REST-Framework-Version`, add them with the [headers property](/2-4-2/connectors/enterprise-connectors/http-rest/httpconnection.md#headers-object) of the connection.

### Reporting Operation Transactions

The Operation Transactions resource reports the progress of a work order operation, for example moving a quantity from the `READY` to the `COMPLETE` dispatch state. Each POST request creates one or more operation transactions.

We define a write endpoint for the API path and a mapping that feeds it from the MQTT topic hierarchy. The HTTP/REST connector expects the request body in the `body` property of the message (see [Publishing Data to REST Servers](/2-4-2/connectors/enterprise-connectors/http-rest.md#publishing-data-to-rest-servers)). The `transform` rule wraps the incoming payload accordingly, so machines can publish their data without knowing about this convention.

{% code lineNumbers="true" %}

```yaml
operationTransactionsEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Http
    connection: !ref oracleFusionConnection
    write:
      path: /operationTransactions

operationTransactionsMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          topic: !sub '${topicRoot}/+site/+area/+line/+cell/work-order-transactions'
        publish:
          endpoint: !ref operationTransactionsEndpoint
        rules:
          - transform:
              expression: '{ "body": $ }'
```

{% endcode %}

Any message published to a matching topic, for example `enterprise/hamburg/machining/line-1/cnc-01/work-order-transactions`, now creates one operation transaction in Oracle Manufacturing. The payload must follow the request schema of the [Operation Transactions resource](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/26b/fasrp/op-operationtransactions-post.html). The dispatch states come from the Oracle lookup type `ORA_WIE_DISPATCH_STATE`:

{% code lineNumbers="true" %}

```json
{
  "OperationTransactionDetail": [
    {
      "OrganizationCode": "PLANT01",
      "WorkOrderNumber": "WO-1001",
      "WoOperationSequenceNumber": 10,
      "FromDispatchState": "READY",
      "ToDispatchState": "COMPLETE",
      "TransactionQuantity": 10,
      "TransactionUOMCode": "EA",
      "TransactionDate": "2026-07-16T10:30:00.000Z"
    }
  ]
}
```

{% endcode %}

### Reporting Material Transactions

The Material Transactions resource works the same way and reports components that are issued to or returned from a work order. The endpoint uses the same connection with a different path, and the mapping listens on the `material-transactions` leaf of the topic hierarchy.

{% code lineNumbers="true" %}

```yaml
materialTransactionsEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Http
    connection: !ref oracleFusionConnection
    write:
      path: /materialTransactions

materialTransactionsMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          topic: !sub '${topicRoot}/+site/+area/+line/+cell/material-transactions'
        publish:
          endpoint: !ref materialTransactionsEndpoint
        rules:
          - transform:
              expression: '{ "body": $ }'
```

{% endcode %}

The payload must follow the request schema of the [Material Transactions resource](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/26b/fasrp/op-materialtransactions-post.html). The item, the subinventory, and the transaction type must exist in your Oracle Fusion Cloud master data:

{% code lineNumbers="true" %}

```json
{
  "MaterialTransactionDetail": [
    {
      "OrganizationCode": "PLANT01",
      "WorkOrderNumber": "WO-1001",
      "WoOperationSequenceNumber": 10,
      "InventoryItemNumber": "ITEM-100",
      "TransactionTypeCode": "MATERIAL_ISSUE",
      "TransactionQuantity": 2,
      "TransactionUnitOfMeasure": "EA",
      "SubinventoryCode": "STORES",
      "TransactionDate": "2026-07-16T10:30:00.000Z"
    }
  ]
}
```

{% endcode %}

### Polling Work Orders

For the opposite direction, a subscribe endpoint polls the Work Orders resource at the configured interval. The `query` property adds the standard Oracle REST query parameters to every request: the `q` parameter filters for released work orders of the configured organization, `onlyData` omits the navigation links from the response, and `limit` caps the page size. The valid work order status codes are available through the `workOrderStatuses` resource of your instance, `ORA_RELEASED` is the seeded code for released work orders.

{% code lineNumbers="true" %}

```yaml
workOrdersEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Http
    connection: !ref oracleFusionConnection
    subscribe:
      path: /workOrders
      interval: !ref pollInterval
      query:
        q: !sub "WorkOrderStatusCode='ORA_RELEASED';OrganizationCode='${organizationCode}'"
        onlyData: 'true'
        limit: '25'

workOrdersMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          endpoint: !ref workOrdersEndpoint
        publish:
          topic: !sub '${topicRoot}/oracle-fusion/work-orders'
```

{% endcode %}

Every poll result is published to the topic `enterprise/oracle-fusion/work-orders` in the standardized wrapper of the HTTP/REST connector (see [Response Message Format](/2-4-2/connectors/enterprise-connectors/http-rest.md#response-message-format)). The `value` property contains the Oracle response with one entry per work order in the `items` array. From there, any other Connectware service can pick up the work orders, for example to display the order queue on a shop floor dashboard.

### Using OAuth 2.0 Instead of Basic Authentication

Basic authentication with a dedicated integration user is the most direct way to connect and is used throughout this guide. Oracle Fusion Cloud also supports token-based authentication through Oracle Identity and Access Management, for example with JWT bearer tokens. If your Oracle environment provides an OAuth token endpoint with client credentials, replace the `auth` property of the connection with the `oauthClientCredentials` property. Connectware then fetches and renews the token automatically. For more information, see [OAuth 2.0 Client Credentials Grant](https://docs.cybus.io/2-4-2/guides/system-connectivity/mes-erp-business-systems/pages/Hij6TsDxB4GxfyynBwLn#oauth-2.0-client-credentials-grant).

## Verifying the Integration

1. Install the service and set the parameters for your Oracle Fusion Cloud instance and integration user.
2. Check that the connection is in the **Connected** state on the service details page in the Admin UI. The connected state confirms that Connectware reaches the Oracle host. Authentication errors appear on the endpoint result topics instead.
3. Open the [Data Explorer](/2-4-2/monitoring/data-explorer.md) and subscribe to `enterprise/oracle-fusion/work-orders`. A message with the released work orders arrives with every polling interval.
4. Publish a test operation transaction to `enterprise/hamburg/machining/line-1/cnc-01/work-order-transactions`, for example with an MQTT client or the Admin UI. Use the work order number and operation sequence of a released work order from the previous step.
5. Inspect the `/res` topic of the operation transactions endpoint in the Data Explorer. On success, the Oracle response contains `"ErrorsExistFlag": false`. If the request fails, the message contains an `error` property with the HTTP status, and business validation errors are listed in the `ErrorMessages` attribute of the Oracle response.
6. In Oracle Fusion Cloud, open the Work Execution work area and check that the completed quantity of the work order operation has increased.

## Service Commissioning File Example

{% file src="/files/HTBz8QvDqPhO7bfYNLGh" %}

{% code title="oracle-fusion-cloud-scm-example.yml" lineNumbers="true" expandable="true" %}

```yaml
---
# ----------------------------------------------------------------------------
# Service Commissioning File
# ----------------------------------------------------------------------------
# Copyright: Cybus GmbH
# Contact: support@cybus.io
# ----------------------------------------------------------------------------
# Oracle Fusion Cloud SCM Integration (Example)
# ----------------------------------------------------------------------------

description: >
  Service commissioning file for the bidirectional integration between
  Connectware and Oracle Fusion Cloud SCM (Example)

metadata:
  name: Oracle Fusion Cloud SCM Integration
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  oracleFusionHost:
    description: Hostname of your Oracle Fusion Cloud instance
    type: string
    default: example.fa.us2.oraclecloud.com

  restApiVersion:
    description: Version of the Oracle Fusion Cloud REST API
    type: string
    default: 11.13.18.05

  integrationUsername:
    description: Username of the Oracle Fusion Cloud integration user
    type: string

  integrationPassword:
    description: Password of the Oracle Fusion Cloud integration user
    type: string

  organizationCode:
    description: Code of the manufacturing organization to poll work orders for
    type: string
    default: PLANT01

  pollInterval:
    description: Polling interval for work orders in milliseconds
    type: integer
    default: 60000

  topicRoot:
    description: Root of the MQTT topic hierarchy
    type: string
    default: enterprise

resources:
  # Connection to the Oracle Fusion Cloud REST APIs using basic authentication
  oracleFusionConnection:
    type: Cybus::Connection
    properties:
      protocol: Http
      connection:
        scheme: https
        host: !ref oracleFusionHost
        port: 443
        prefix: !sub '/fscmRestApi/resources/${restApiVersion}'
        auth:
          username: !ref integrationUsername
          password: !ref integrationPassword

  # Reports work order operation transactions to Oracle Manufacturing
  operationTransactionsEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Http
      connection: !ref oracleFusionConnection
      write:
        path: /operationTransactions

  operationTransactionsMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            topic: !sub '${topicRoot}/+site/+area/+line/+cell/work-order-transactions'
          publish:
            endpoint: !ref operationTransactionsEndpoint
          rules:
            - transform:
                expression: '{ "body": $ }'

  # Reports material transactions (component issues and returns)
  materialTransactionsEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Http
      connection: !ref oracleFusionConnection
      write:
        path: /materialTransactions

  materialTransactionsMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            topic: !sub '${topicRoot}/+site/+area/+line/+cell/material-transactions'
          publish:
            endpoint: !ref materialTransactionsEndpoint
          rules:
            - transform:
                expression: '{ "body": $ }'

  # Polls released work orders from Oracle Manufacturing
  workOrdersEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Http
      connection: !ref oracleFusionConnection
      subscribe:
        path: /workOrders
        interval: !ref pollInterval
        query:
          q: !sub "WorkOrderStatusCode='ORA_RELEASED';OrganizationCode='${organizationCode}'"
          onlyData: 'true'
          limit: '25'

  workOrdersMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref workOrdersEndpoint
          publish:
            topic: !sub '${topicRoot}/oracle-fusion/work-orders'
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybus.io/2-4-2/guides/system-connectivity/mes-erp-business-systems/oracle-fusion-cloud-scm-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.