Jump to

• Request
• Response
• Examples

Bulk update resource inventories

post

/rest/ofscCore/v1/resources/custom-actions/bulkUpdateInventories

This operation creates, updates, or deletes inventories of multiple resources in a single call. Only inventories with status as 'resource' are created, deleted, or updated. Inventories with status as 'installed' or 'deinstalled' are ignored. Each resource pool is processed independently - inventory will not be moved between different resources. To "move" a piece of inventory it is necessary to specifically create it in one resource pool and remove from another.

Error Handling:

• If the request size is greater than 5 MB, then the API fails with the HTTP status '413 Request entity too large' error.
• If the swagger validation fails, then the entire request fails with the HTTP status '400 Bad Request' error. Examples of such cases are:
  • A required field is not specified.
  • The request is not a valid JSON.
• The operation returns HTTP status '200 OK', even if individual inventories are not created for some reason. Verify the response to identify the operations that succeeded and the operations that failed. Examples of such cases are:
  • The resource ID does not exist
  • The resource does have inventories (not a technician).
  • The inventory type does not exist.
  • An invalid value is specified for an 'enum' custom property.
  • A string value is specified for a custom property having data type as integer.

Permissions:

The permissions 'Core API : Resource' and 'Core API : Inventory' have to be set to 'ReadWrite' for this API to work.

Request

Body ()

Root Schema : Bulk update resource inventories request schema

Type: object

Title: Bulk update resource inventories request schema

Show Source

• resources(required): array Resources
  Title: Resources

  An array of resource IDs and their related inventory information.

{
    "title":"Bulk update resource inventories request schema",
    "type":"object",
    "properties":{
        "resources":{
            "items":{
                "$ref":"#/definitions/bulkUpdateResourceInventoriesRequestResourceSchema"
            },
            "type":"array",
            "description":"An array of resource IDs and their related inventory information.",
            "title":"Resources"
        }
    },
    "required":[
        "resources"
    ]
}

Nested Schema : Resources

Type: array

Title: Resources

An array of resource IDs and their related inventory information.

Show Source

• Array of: object Resource
  Title: Resource

{
    "items":{
        "$ref":"#/definitions/bulkUpdateResourceInventoriesRequestResourceSchema"
    },
    "type":"array",
    "description":"An array of resource IDs and their related inventory information.",
    "title":"Resources"
}

Nested Schema : Resource

Type: object

Title: Resource

Show Source

• identifySerializedInventoryBy: string
  Title: Identify Serialized Inventory By

  Allowed Values: [ "serialNumber", "typeAndSerial", "typeAndModelAndSerial" ]

  This field determines the key for identifying serialized inventory within a resource pool. The possible values of this field are:

  • serialNumber - When serialNumber is the only field required for identifying serialized inventories for a particular resource. This is the default value.
  • typeAndSerial - When two fields (inventoryType + serialNumber) are used as the key for identifying serialized inventories for a particular resource.
  • typeAndModelAndSerial - When three fields (inventoryType + model + serialNumber) are used as the key for identifying serialized inventories for a particular resource. The model value is stored in a custom property, which is configured for each inventory type. If inventory type was not provided, the model value is considered as empty.
• inventories(required): array Inventories
  Title: Inventories

  An array containing inventory objects. If this array is empty and the 'operationType' is 'replace', then all the existing inventories for the specified resource are erased.
• inventoryPropertiesUpdateMode: string
  Title: Inventory Properties Update Mode

  Allowed Values: [ "keepProperties", "eraseProperties" ]

  The processing mode for updating the properties of each inventory item in the 'inventories' array. The possible values of this parameter are:

  • keepProperties: The specified inventory properties are updated and the properties that are not specified are retained.
  • eraseProperties: The specified inventory properties are replaced and the properties that are not specified are erased. This is the default value of the parameter.
• operationType: string
  Title: Operation Type

  Allowed Values: [ "update", "replace" ]

  The type of the operation. The possible values of this parameter are:

  • replace - Existing inventories that are not specified in the request are deleted. Inventories that are specified in the request and exist in Oracle Field Service are updated. Inventories that are specified in the request but do not exist in Oracle Field Service are added. This is the default value.
  • update - Existing inventories that are not specified in the request are not deleted. Inventories that are specified in the request and exist in Oracle Field Service are updated. Inventories that are specified in the request but do not exist in Oracle Field Service are added.
• resourceId(required): string
  Title: Resource ID

  Minimum Length: 1

  The resource ID in the external system.

{
    "title":"Resource",
    "type":"object",
    "properties":{
        "resourceId":{
            "type":"string",
            "description":"The resource ID in the external system.",
            "minLength":1,
            "title":"Resource ID"
        },
        "operationType":{
            "type":"string",
            "description":"The type of the operation. The possible values of this parameter are:<ul><li>replace - Existing inventories that are not specified in the request are deleted. Inventories that are specified in the request and exist in Oracle Field Service  are updated. Inventories that are specified in the request but do not exist in Oracle Field Service are added. This is the default value.</li><li>update - Existing inventories that are not specified in the request are not deleted. Inventories that are specified in the request and exist in Oracle Field Service are updated. Inventories that are specified in the request but do not exist in Oracle Field Service are added.</li></ul>",
            "enum":[
                "update",
                "replace"
            ],
            "title":"Operation Type"
        },
        "identifySerializedInventoryBy":{
            "type":"string",
            "description":"This field determines the key for identifying serialized inventory within a resource pool. The possible values of this field are:<ul><li> serialNumber - When serialNumber is the only field required for identifying serialized inventories for a particular resource. This is the default value.</li><li> typeAndSerial -  When two fields (inventoryType + serialNumber) are used as the key for identifying serialized inventories for a particular resource.</li><li> typeAndModelAndSerial - When three fields (inventoryType + model + serialNumber) are used as the key for identifying serialized inventories for a particular resource. The model value is stored in a custom property, which is configured for each inventory type. If inventory type was not provided, the model value is considered as empty.</li></ul>",
            "enum":[
                "serialNumber",
                "typeAndSerial",
                "typeAndModelAndSerial"
            ],
            "title":"Identify Serialized Inventory By"
        },
        "inventoryPropertiesUpdateMode":{
            "$ref":"#/definitions/inventoryPropertiesUpdateMode"
        },
        "inventories":{
            "items":{
                "$ref":"#/definitions/bulkUpdateResourceInventoriesRequestInventorySchema"
            },
            "type":"array",
            "description":"An array containing inventory objects. If this array is empty and the 'operationType' is 'replace', then all the existing inventories for the specified resource are erased.",
            "title":"Inventories"
        }
    },
    "required":[
        "resourceId",
        "inventories"
    ]
}

Nested Schema : Inventories

Type: array

Title: Inventories

An array containing inventory objects. If this array is empty and the 'operationType' is 'replace', then all the existing inventories for the specified resource are erased.

Show Source

• Array of: object Inventory
  Title: Inventory

{
    "items":{
        "$ref":"#/definitions/bulkUpdateResourceInventoriesRequestInventorySchema"
    },
    "type":"array",
    "description":"An array containing inventory objects. If this array is empty and the 'operationType' is 'replace', then all the existing inventories for the specified resource are erased.",
    "title":"Inventories"
}

Nested Schema : Inventory

Type: object

Title: Inventory

Show Source

• inventoryType: string
  Title: Inventory Type

  The label of the inventory type as defined in Oracle Field Service.

  • For non-serialized inventories, this parameter along with the model is used as the key to determine the existing inventory that is replaced.
• quantity: number
  Title: Quantity

  The quantity of the non-serialized inventory.

  • For serialized inventories, the value of this parameter is set to 1.
  • For non-serialized inventories, this parameter is saved. The value can be positive, negative, or zero.

  The default value is 1.
• serialNumber: string
  Title: Serial Number

  The serial number of the inventory.

  • For serialized inventories, this is the unique key (or a part of the unique key along with other fields) of an inventory for a particular resource. This key is determined by the value of the 'identifySerializedInventoryBy' parameter.
  • For non-serialized inventories, the value of this parameter can be specified but it does not hold any meaning.

{
    "title":"Inventory",
    "type":"object",
    "properties":{
        "serialNumber":{
            "type":"string",
            "description":"The serial number of the inventory.<ul><li>For serialized inventories, this is the unique key (or a part of the unique key along with other fields) of an inventory for a particular resource. This key is determined by the value of the 'identifySerializedInventoryBy' parameter.</li><li>For non-serialized inventories, the value of this parameter can be specified but it does not hold any meaning.</li></ul>",
            "title":"Serial Number"
        },
        "quantity":{
            "type":"number",
            "description":"The quantity of the non-serialized inventory.<ul><li>For serialized inventories, the value of this parameter is set to 1.</li><li>For non-serialized inventories, this parameter is saved. The value can be positive, negative, or zero.</li></ul> The default value is 1.",
            "title":"Quantity"
        },
        "inventoryType":{
            "type":"string",
            "description":"The label of the inventory type as defined in Oracle Field Service.<ul><li>For non-serialized inventories, this parameter along with the model is used as the key to determine the existing inventory that is replaced.</li></ul>",
            "title":"Inventory Type"
        }
    }
}

Back to Top

Response

Supported Media Types

• application/json

200 Response

This section describes the 200 status response for this operation.

Body ()

Root Schema : Bulk Update Resource Inventories Response Schema

Type: object

Title: Bulk Update Resource Inventories Response Schema

Show Source

• created: integer
  Title: Created

  The number of inventories created by the API call.
• deleted: integer
  Title: Deleted

  The number of inventories deleted by the API call.
• itemsFailed: integer
  Title: Items Failed

  The number of items of the 'resources' array in the request that failed.
• results: array Results
  Title: Results

  The array of results. Each item in the 'resources' array in the request has a corresponding item in the 'results' array. The 'results' array items are in the same order as the 'resources' array items.
• updated: integer
  Title: Updated

  The number of inventories updated by the API call.

{
    "title":"Bulk Update Resource Inventories Response Schema",
    "type":"object",
    "properties":{
        "created":{
            "type":"integer",
            "title":"Created",
            "description":"The number of inventories created by the API call."
        },
        "updated":{
            "type":"integer",
            "title":"Updated",
            "description":"The number of inventories updated by the API call."
        },
        "deleted":{
            "type":"integer",
            "title":"Deleted",
            "description":"The number of inventories deleted by the API call."
        },
        "itemsFailed":{
            "type":"integer",
            "title":"Items Failed",
            "description":"The number of items of the 'resources' array in the request that failed."
        },
        "results":{
            "items":{
                "$ref":"#/definitions/bulkUpdateResourceInventoriesResponseResultSchema"
            },
            "type":"array",
            "description":"The array of results. Each item in the 'resources' array in the request has a corresponding item in the 'results' array. The 'results' array items are in the same order as the 'resources' array items.",
            "title":"Results"
        }
    }
}

Nested Schema : Results

Type: array

Title: Results

The array of results. Each item in the 'resources' array in the request has a corresponding item in the 'results' array. The 'results' array items are in the same order as the 'resources' array items.

Show Source

• Array of: object Result
  Title: Result

{
    "items":{
        "$ref":"#/definitions/bulkUpdateResourceInventoriesResponseResultSchema"
    },
    "type":"array",
    "description":"The array of results. Each item in the 'resources' array in the request has a corresponding item in the 'results' array. The 'results' array items are in the same order as the 'resources' array items.",
    "title":"Results"
}

Nested Schema : Result

Type: object

Title: Result

Show Source

• created: integer
  Title: Created

  The number of inventories created for the specific resource.
• deleted: integer
  Title: Deleted

  The number of inventories deleted for the specific resource.
• errors: array Errors
  Title: Errors

  This field is returned only if any item fails. It contains human-readable description of the error such as type, title, HTTP status, and so on.
• resourceId: string
  Title: Resource ID

  The resource ID for which the inventories were updated, created, or deleted.
• updated: integer
  Title: Updated

  The number of inventories updated for the specific resource.

{
    "title":"Result",
    "type":"object",
    "properties":{
        "resourceId":{
            "type":"string",
            "description":"The resource ID for which the inventories were updated, created, or deleted.",
            "title":"Resource ID"
        },
        "created":{
            "type":"integer",
            "title":"Created",
            "description":"The number of inventories created for the specific resource."
        },
        "updated":{
            "type":"integer",
            "title":"Updated",
            "description":"The number of inventories updated for the specific resource."
        },
        "deleted":{
            "type":"integer",
            "title":"Deleted",
            "description":"The number of inventories deleted for the specific resource."
        },
        "errors":{
            "items":{
                "$ref":"#/definitions/Error"
            },
            "type":"array",
            "description":"This field is returned only if any item fails. It contains human-readable description of the error such as type, title, HTTP status, and so on.",
            "title":"Errors"
        }
    }
}

Nested Schema : Errors

Type: array

Title: Errors

This field is returned only if any item fails. It contains human-readable description of the error such as type, title, HTTP status, and so on.

Show Source

• Array of: object Error

{
    "items":{
        "$ref":"#/definitions/Error"
    },
    "type":"array",
    "description":"This field is returned only if any item fails. It contains human-readable description of the error such as type, title, HTTP status, and so on.",
    "title":"Errors"
}

Nested Schema : Error

Type: object

Show Source

• detail: string
  The detailed description of this error.
• status: string
  The HTTP status code of this error.
• title(required): string
  The brief description of this error.
• type(required): string
  The URL of the web page containing more details about this error.

{
    "properties":{
        "type":{
            "type":"string",
            "description":"The URL of the web page containing more details about this error."
        },
        "title":{
            "type":"string",
            "description":"The brief description of this error."
        },
        "status":{
            "type":"string",
            "description":"The HTTP status code of this error."
        },
        "detail":{
            "type":"string",
            "description":"The detailed description of this error."
        }
    },
    "required":[
        "type",
        "title"
    ]
}

Default Response

This section describes the default error response for this operation.

Body ()

Root Schema : Error

Type: object

Show Source

• detail: string
  The detailed description of this error.
• status: string
  The HTTP status code of this error.
• title(required): string
  The brief description of this error.
• type(required): string
  The URL of the web page containing more details about this error.

{
    "properties":{
        "type":{
            "type":"string",
            "description":"The URL of the web page containing more details about this error."
        },
        "title":{
            "type":"string",
            "description":"The brief description of this error."
        },
        "status":{
            "type":"string",
            "description":"The HTTP status code of this error."
        },
        "detail":{
            "type":"string",
            "description":"The detailed description of this error."
        }
    },
    "required":[
        "type",
        "title"
    ]
}

Back to Top

Examples

The following example shows how to create or update resource inventory in bulk for the specified resources with the specified inventories by submitting a POST request on the REST resource using cURL:

cURL command Example

curl -s -u "<CLIENT-ID>@<INSTANCE-NAME>:<CLIENT-SECRET>" --url "https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/resources/custom-actions/bulkUpdateInventories" -X POST -d '
{
    "resources": [
        {
            "resourceId": "11102",
            "inventories": [
                {
                    "inventoryType": "NORMAL",
                    "serialNumber": "XA1234567892",
                    "testpropInvString" : "Blarg"
                },
                {
                    "inventoryType": "RG6BLK",
                    "inventory_model": "Z222",
                    "testpropInvString" : "Blarg 2",
                    "quantity": 8
                },
                {
                    "inventoryType": "RG6BLK",
                    "inventory_model": "X333",
                    "quantity": 5
                }
            ]
        },
        {
            "resourceId": "11105",
            "inventories": [
                {
                    "inventoryType": "xx",
                    "serialNumber": "XA1234567892",
                    "testpropInvString" : "Blarg"
                },
                {
                    "inventoryType": "RG6BLK",
                    "inventory_model": "Z222",
                    "testpropInvString" : "Blarg 2",
                    "quantity": 8
                },
                {
                    "inventoryType": "RG6BLK",
                    "inventory_model": "X333",
                    "quantity": 5
                }
            ]
        }
    ]
}'

Response Header Example

The following shows an example of the response header.

HTTP/1.1 200 OK
Server: nginx/1.2.7
Date: Mon, 18 Dec 2017 02:20:33 GMT
Content-Type: application/json; charset=utf-8

Response Body Example

The following shows an example of the response body in JSON format, where one request item was processed successfully while the other request item failed:

{
    "created": 0,
    "updated": 3,
    "deleted": 0,
    "itemsFailed": 1,
    "results": [
        {
            "resourceId": "11102",
            "created": 0,
            "updated": 3,
            "deleted": 0
        },
        {
            "resourceId": "11105",
            "error": {
                "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10",
                "title": "Conflict",
                "status": "409",
                "detail": "Invalid value of field 'inventories/0/inventoryType'. Value: 'xx'"
            }
        }
    ]
}

Back to Top