Jump to

• Request
• Response
• Examples

Find resources for urgent assignment

post

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

This operation retrieves a list of resources that can immediately perform an activity based on the criteria specified in the request.

The resources matching the specified criteria are returned in the response if the information about their location is not older then one hour.

Request

Body ()

Root Schema : Find Matching Resources for Urgent Assignment Request

Type: object

Title: Find Matching Resources for Urgent Assignment Request

The schema of the request body object for this operation.

Show Source

• activity(required): activity
  The properties of the activity. This is a required parameter.
• parentResources: array Parent Resource ID
  Title: Parent Resource ID

  The list of identifiers of the parent resources.

  If this parameter is specified, then the operation evaluates only the children of the specified resources and their descendants. If this parameter is not specified, then all resources are evaluated and returned in the response.

• radius: integer
  Title: Radius

  Minimum Value: 0

  Maximum Value: 300000

  The radius of area (in meters) where the search is performed.

  If the value is not specified in the request, then it defaults to 100000 meters.

• resourceFields: array Resource Fields
  Title: Resource Fields

  The resource fields to be returned in the response.

  If this parameter is not specified in the request, then the default resource fields, 'resourceId', 'resourceInternalId', 'name', 'resourceType' are returned.

  Using this parameter, it is possible to specify the list of fields that are needed for the integration flow to increase the performance and reduce the traffic.

  When the resource fields are specified, only the 'resourceId' field and the requested fields are returned.

  If incorrect resource fields are specified, then the 400 error code is returned.

{
    "type":"object",
    "title":"Find Matching Resources for Urgent Assignment Request",
    "properties":{
        "activity":{
            "description":"The properties of the activity. This is a required parameter.",
            "allOf":[
                {
                    "$ref":"#/definitions/activityFMRSchema"
                }
            ],
            "required":[
                "activityType",
                "longitude",
                "latitude"
            ]
        },
        "radius":{
            "type":"integer",
            "minimum":0,
            "maximum":300000,
            "description":"The radius of area (in meters) where the search is performed.<p> If the value is not specified in the request, then it defaults to 100000 meters.</p>",
            "title":"Radius"
        },
        "resourceFields":{
            "title":"Resource Fields",
            "description":"The resource fields to be returned in the response.<p>If this parameter is not specified in the request, then the default resource fields,  'resourceId', 'resourceInternalId', 'name', 'resourceType' are returned.</p><p>Using this parameter, it is possible to specify the list of fields that are needed for the integration flow to increase the performance and reduce the traffic.</p><p>When the resource fields are specified, only the 'resourceId' field and the requested fields are returned.</p><p>If incorrect resource fields are specified, then the 400 error code is returned.</p>",
            "type":"array",
            "items":{
                "type":"string"
            }
        },
        "parentResources":{
            "type":"array",
            "items":{
                "type":"string"
            },
            "description":"The list of identifiers of the parent resources.<p>If this parameter is specified, then the operation evaluates only the children of the specified resources and their descendants. If this parameter is not specified, then all resources are evaluated and returned in the response.</p>",
            "title":"Parent Resource ID"
        }
    },
    "required":[
        "activity"
    ],
    "description":"The schema of the request body object for this operation."
}

Nested Schema : activity

The properties of the activity. This is a required parameter.

Match All

The properties of the activity. This is a required parameter.

Show Source

• object New Activity Properties
  Title: New Activity Properties

  The properties of the new activity.

{
    "description":"The properties of the activity. This is a required parameter.",
    "allOf":[
        {
            "$ref":"#/definitions/activityFMRSchema"
        }
    ],
    "required":[
        "activityType",
        "longitude",
        "latitude"
    ]
}

Nested Schema : Parent Resource ID

Type: array

Title: Parent Resource ID

The list of identifiers of the parent resources.

If this parameter is specified, then the operation evaluates only the children of the specified resources and their descendants. If this parameter is not specified, then all resources are evaluated and returned in the response.

Show Source

• Array of: string

{
    "type":"array",
    "items":{
        "type":"string"
    },
    "description":"The list of identifiers of the parent resources.<p>If this parameter is specified, then the operation evaluates only the children of the specified resources and their descendants. If this parameter is not specified, then all resources are evaluated and returned in the response.</p>",
    "title":"Parent Resource ID"
}

Nested Schema : Resource Fields

Type: array

Title: Resource Fields

The resource fields to be returned in the response.

If this parameter is not specified in the request, then the default resource fields, 'resourceId', 'resourceInternalId', 'name', 'resourceType' are returned.

Using this parameter, it is possible to specify the list of fields that are needed for the integration flow to increase the performance and reduce the traffic.

When the resource fields are specified, only the 'resourceId' field and the requested fields are returned.

If incorrect resource fields are specified, then the 400 error code is returned.

Show Source

• Array of: string

{
    "title":"Resource Fields",
    "description":"The resource fields to be returned in the response.<p>If this parameter is not specified in the request, then the default resource fields,  'resourceId', 'resourceInternalId', 'name', 'resourceType' are returned.</p><p>Using this parameter, it is possible to specify the list of fields that are needed for the integration flow to increase the performance and reduce the traffic.</p><p>When the resource fields are specified, only the 'resourceId' field and the requested fields are returned.</p><p>If incorrect resource fields are specified, then the 400 error code is returned.</p>",
    "type":"array",
    "items":{
        "type":"string"
    }
}

Nested Schema : New Activity Properties

Type: object

Title: New Activity Properties

The properties of the new activity.

Show Source

• accessSchedule: string
  Title: Access Schedule

  The schedule (that is, the set of time intervals or access hours, two intervals per week day) when the asset or the activity location is accessible. Work must start and complete during this interval. It is generally not possible to work beyond the access hours. Maximum field length is 1020.

  Access Schedule Field Format
  This field is a string, which contains an inner json object (encoded as a string). For example, "accessSchedule": "{\"schedule\":[{\"daysOfWeek\":[\"Mon\",\"Tue\"],\"hours\":[[\"07:00\",\"12:00\"]]}]}"

  The inner json object has the following schema:

  {
  "type": "object",
  "properties": {
  "schedule": {
  "type": "array",
  "items": {
  "type": "object",
  "properties": {
  "daysOfWeek": {
  "type": "array",
  "items": {
  "type": "string",
  "enum": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ]
  }
  },
  "hours": {
  "type": "array",
  "items": {
  "type": "array",
  "items": { "type": "string" }
  }
  }
  }
  }
  },
  "exceptDates": {
  "type": "array",
  "items": { "type": "string" }
  }
  }
  }

• activityType: string
  Title: Activity Type

  The label of the activity type. Based on the activity type, predefined company-specific rules are applied when processing an activity. Predefined company-specific rules cover the following:

  • The resources that the activity can be assigned to.
  • The activity processing details.
  • The interaction of the activity with different modules of Oracle Field Service.
• apptNumber: string
  Title: Appt Number

  The apptNumber parameter may be used by integrations to store the identifier of the activity in the origin system. This field has no business significance in Oracle Field Service and can be left empty. Maximum field length is 40.
• city: string
  Title: City

  The city of the customer. This field is used for geocoding and must contain a valid address. Maximum field length is 60.
• country_code: string
  Title: Country Code

  The code of the country where the activity is scheduled.
• customerCell: string
  Title: Customer Cell

  The cell phone number of the customer. The phone number is saved in Oracle Field Service with the '+' symbol and all other non-digit characters are removed. For example, if you enter the phone number as [phone]_42, it is saved in Oracle Field Service as [phone]. Maximum field length is 240.
• customerEmail: string
  Title: Customer Email

  The email address of the customer. Maximum field length is 320.
• customerName: string
  Title: Customer Name

  The name of the customer. Maximum field length is 420.
• customerNumber: string
  Title: Customer Number

  The account number of the customer. This field is used by integrations as a placeholder for the external identifier of the Account ID in the application. This parameter has no business significance in Oracle Field Service and can be left empty. Maximum field length is 40.
• customerPhone: string
  Title: Customer Phone

  The regular (land) phone number of the customer. The phone number is saved in Oracle Field Service with the '+' symbol and all other non-digit characters are removed. For example, if you enter the phone number as [phone]_42, it is saved in Oracle Field Service as [phone]. Maximum field length is 240.
• date: string
  Title: Date

  The date on which the activity is scheduled. This field is not present in the response, if the activity is not scheduled for any particular date.
• deliveryWindowEnd: string
  Title: Delivery Window End

  The time when the activity delivery window ends. The time is displayed in the time zone of the resource to which the activity is assigned, and is in 'HH:MM:SS' format.
• deliveryWindowStart: string
  Title: Delivery Window Start

  The time when the activity delivery window starts. The time is displayed in the time zone of the resource to which the activity is assigned, and is in 'HH:MM:SS' format.
• duration: integer
  Title: Duration

  Estimated activity duration in minutes. The duration specified in request will only be applied if the 'Calculate activity duration using statistics' checkbox is unchecked for the Activity Type of the activity being created/updated. For segmentable activities this field is only used when a new activity is created. To change the length of the segmentable activities use the field "multidayTimeToComplete" instead.
• language: string
  Title: Language

  The preferred language of the customer. This parameter returns two-character code (e.g. "en") in API responses. To obtain ISO code of the language (e.g. "en-US") read the "languageISO" parameter. In the requests this parameter accepts both formats (e.g. "en" or "en-US"). It is recommended to use ISO format. The language codes listed on: Supported Language Codes.
• languageISO: string
  Title: Language ISO

  The preferred language of the customer. This parameter is only present in the responses and will be ignored if it is present in a request. To update language use the parameter "language". The language codes listed on: Supported Language Codes.
• latitude: number
  Title: Latitude

  Minimum Value: -90

  Maximum Value: 90

  The geographic coordinates that specify the location of the activity.
• longitude: number
  Title: Longitude

  Minimum Value: -180

  Maximum Value: 180

  The geographic coordinates that specify the location of the activity.
• points: integer
  Title: Points

  Minimum Value: 0

  Maximum Value: 65535

  The cost of the activity in 'points'. This field is intended for use by the Routing module.
• postalCode: string
  Title: Postal Code

  The postal code of the customer. This field is used for geocoding and must contain a valid address. Maximum field length is 60.
• reminderTime: integer
  Title: Reminder Time

  The number of minutes before the activity start time the customer must be notified of the activity.
• requiredInventories: array requiredInventories
  List of inventories required by activity. Max 100 items.
• resourceId: string
  Title: Resource ID

  The identifier of the resource to which this activity is assigned. This field is not returned if the resource ID is empty.

  Note: Do not use empty strings in requests.

• resourcePreferences: array resourcePreferences
  List of resource preferences for the activity. Max 100 items.
• serviceWindowEnd: string
  Title: Service Window End

  The time when the service window ends for the activity. The time is displayed in 'HH:MM:SS' format.

  If the activity type feature 'SLA and Service window use customer time zone' is enabled, then the service window is accepted in the time zone of the customer. If it is not enabled, then the Service Window is accepted in the time zone of the resource to which the activity is currently assigned.

  If the activity is later assigned to another resource and the activity type feature 'SLA and Service window use customer time zone' is enabled, then the Service Window is recalculated so that the fields are not changed in the customer's time zone, but they are changed in the time zone of the new resource.

• serviceWindowStart: string
  Title: Service Window Start

  The time when the service window starts for the activity. The time is displayed in 'HH:MM:SS' format.

  If the activity type feature 'SLA and Service window use customer time zone' is enabled, then the service window is accepted in the time zone of the customer. If it is not enabled, then the Service Window is accepted in the time zone of the resource to which the activity is currently assigned.

  If the activity is later assigned to another resource and the activity type feature 'SLA and Service window use customer time zone' is enabled, then the Service Window is recalculated so that the fields are not changed in the customer's time zone, but they are changed in the time zone of the new resource.

• setPositionInRoute: object Set Position in Route
  Title: Set Position in Route

  The value of this element determines the position of the activity in the route. If this element is present then activity will be put to specified position in route. The parameter is optional, if it is absent then the value "position: byServiceWindow" is used.
• setTravelTime: object Set Travel Time
  Title: Set Travel Time

  The objects used to set the travel time of the activity. The travel time is set only if the specified previousActivity/previousActivityId is ordered before the activity for which the travel time is set.
• slaWindowEnd: string
  Title: Sla Window End

  The time when the service level agreement (SLA) window ends. The time is displayed in 'YYYY-MM-DD HH:MM:SS' format.

  If the activity type feature 'SLA and Service window use customer time zone' is enabled, then the SLA is accepted in the time zone of the customer. If it is not enabled, then the SLA is accepted in the time zone of the resource to which the activity is currently assigned.

  If the activity is later assigned to another resource and the activity type feature 'SLA and Service window use customer time zone' is enabled, then the SLA is recalculated so that the fields are not changed in the customer's time zone, but they are changed in the time zone of the new resource.

• slaWindowStart: string
  Title: Sla Window Start

  The time when the service level agreement (SLA) window starts. The time is displayed in 'YYYY-MM-DD HH:MM:SS' format.

  If the activity type feature 'SLA and Service window use customer time zone' is enabled, then the SLA is accepted in the time zone of the customer. If it is not enabled, then the SLA is accepted in the time zone of the resource to which the activity is currently assigned.

  If the activity is later assigned to another resource and the activity type feature 'SLA and Service window use customer time zone' is enabled, then the SLA is recalculated so that the fields are not changed in the customer's time zone, but they are changed in the time zone of the new resource.

• stateProvince: string
  Title: State or Province

  The state or province of the customer. This field is used for geocoding and must contain a valid address. Maximum field length is 60.
• streetAddress: string
  Title: Street Address

  The street address of the customer. This field is used for geocoding and must contain a valid address. Maximum field length is 240.
• teamResourceId: string
  Title: Team Resource ID

  The identifier of the team resource for a teamwork activity.
• timeOfBooking: string
  Title: Time of Booking

  The time when the customer booked the activity. The time is displayed in the time zone of the customer.
• timeSlot: string
  Title: Time Slot

  The time slot during which the activity is completed. Time Slot also indicates the service window for the activity. This time is displayed in the time zone of the resource to which the activity is assigned.
• timeZone: string
  Title: Time Zone

  The name of the customer's time zone. By default, the time zone of the resource (to which the activity is assigned) is used.

  This parameter accepts both Oracle Field Service time zone names (for example, Eastern) and IANA standard time zone names (for example, America/New_York). It is recommended that you specify IANA names. For a list of supported time zones, see Supported Time Zones.

{
    "title":"New Activity Properties",
    "properties":{
        "customerEmail":{
            "type":"string",
            "description":"The email address of the customer. Maximum field length is 320.",
            "title":"Customer Email"
        },
        "accessSchedule":{
            "$ref":"#/definitions/activityAccessSchedule"
        },
        "timeZone":{
            "type":"string",
            "description":"<p>The name of the customer's time zone. By default, the time zone of the resource (to which the activity is assigned) is used.</p><p>This parameter accepts both Oracle Field Service time zone names (for example, Eastern) and IANA standard time zone names (for example, America/New_York). It is recommended that you specify IANA names. For a list of supported time zones, see <a href= http://docs.oracle.com/cloud/latest/fieldservicecs_gs/CXFSC/OFSC_Supported_Time_Zones.html>Supported Time Zones</a>.</p>",
            "title":"Time Zone"
        },
        "date":{
            "type":"string",
            "description":"The date on which the activity is scheduled. This field is not present in the response, if the activity is not scheduled for any particular date.",
            "title":"Date"
        },
        "serviceWindowStart":{
            "$ref":"#/definitions/serviceWindowStartInput"
        },
        "serviceWindowEnd":{
            "$ref":"#/definitions/serviceWindowEndInput"
        },
        "slaWindowStart":{
            "$ref":"#/definitions/slaWindowStartInput"
        },
        "slaWindowEnd":{
            "$ref":"#/definitions/slaWindowEndInput"
        },
        "teamResourceId":{
            "type":"string",
            "description":"The identifier of the team resource for a teamwork activity.",
            "title":"Team Resource ID"
        },
        "deliveryWindowStart":{
            "type":"string",
            "description":"The time when the activity delivery window starts. The time is displayed in the time zone of the resource to which the activity is assigned, and is in 'HH:MM:SS' format.",
            "title":"Delivery Window Start"
        },
        "city":{
            "type":"string",
            "description":"The city of the customer. This field is used for geocoding and must contain a valid address. Maximum field length is 60.",
            "title":"City"
        },
        "customerName":{
            "type":"string",
            "description":"The name of the customer. Maximum field length is 420.",
            "title":"Customer Name"
        },
        "timeOfBooking":{
            "type":"string",
            "description":"The time when the customer booked the activity. The time is displayed in the time zone of the customer.",
            "title":"Time of Booking"
        },
        "stateProvince":{
            "type":"string",
            "description":"The state or province of the customer. This field is used for geocoding and must contain a valid address. Maximum field length is 60.",
            "title":"State or Province"
        },
        "streetAddress":{
            "type":"string",
            "description":"The street address of the customer. This field is used for geocoding and must contain a valid address. Maximum field length is 240.",
            "title":"Street Address"
        },
        "longitude":{
            "type":"number",
            "minimum":-180,
            "maximum":180,
            "description":"The geographic coordinates that specify the location of the activity.",
            "title":"Longitude"
        },
        "duration":{
            "$ref":"#/definitions/durationInput"
        },
        "points":{
            "type":"integer",
            "minimum":0,
            "maximum":65535,
            "description":"The cost of the activity in 'points'. This field is intended for use by the Routing module.",
            "title":"Points"
        },
        "resourceId":{
            "type":"string",
            "description":"<p>The identifier of the resource to which this activity is assigned. This field is not returned if the resource ID is empty.</p><p><b>Note:</b> Do not use empty strings in requests.</p>",
            "title":"Resource ID"
        },
        "reminderTime":{
            "type":"integer",
            "description":"The number of minutes before the activity start time the customer must be notified of the activity.",
            "title":"Reminder Time"
        },
        "country_code":{
            "type":"string",
            "description":"The code of the country where the activity is scheduled.",
            "title":"Country Code"
        },
        "activityType":{
            "type":"string",
            "description":"<p>The label of the activity type. Based on the activity type, predefined company-specific rules are applied when processing an activity. Predefined company-specific rules cover the following:</p><ul><li>The resources that the activity can be assigned to.</li><li>The activity processing details.</li><li>The interaction of the activity with different modules of Oracle Field Service.</li></ul>",
            "title":"Activity Type"
        },
        "apptNumber":{
            "type":"string",
            "description":"The apptNumber parameter may be used by integrations to store the identifier of the activity in the origin system. This field has no business significance in Oracle Field Service and can be left empty. Maximum field length is 40.",
            "title":"Appt Number"
        },
        "deliveryWindowEnd":{
            "type":"string",
            "description":"The time when the activity delivery window ends. The time is displayed in the time zone of the resource to which the activity is assigned, and is in 'HH:MM:SS' format.",
            "title":"Delivery Window End"
        },
        "language":{
            "type":"string",
            "description":"The preferred language of the customer. This parameter returns two-character code (e.g. \"en\") in API responses. To obtain ISO code of the language (e.g. \"en-US\") read the \"languageISO\" parameter. In the requests this parameter accepts both formats (e.g. \"en\" or \"en-US\"). It is recommended to use ISO format. The language codes listed on: <a href=\"OFSC_Supported_Language_Codes.html\">Supported Language Codes</a>.",
            "title":"Language"
        },
        "languageISO":{
            "type":"string",
            "description":"The preferred language of the customer. This parameter is only present in the responses and will be ignored if it is present in a request. To update language use the parameter \"language\". The language codes listed on:  <a href=\"OFSC_Supported_Language_Codes.html\">Supported Language Codes</a>.",
            "title":"Language ISO"
        },
        "postalCode":{
            "type":"string",
            "description":"The postal code of the customer. This field is used for geocoding and must contain a valid address. Maximum field length is 60.",
            "title":"Postal Code"
        },
        "timeSlot":{
            "type":"string",
            "description":"The time slot during which the activity is completed. Time Slot also indicates the service window for the activity. This time is displayed in the time zone of the resource to which the activity is assigned.",
            "title":"Time Slot"
        },
        "latitude":{
            "type":"number",
            "minimum":-90,
            "maximum":90,
            "description":"The geographic coordinates that specify the location of the activity.",
            "title":"Latitude"
        },
        "customerCell":{
            "type":"string",
            "description":"The cell phone number of the customer. The phone number is saved in Oracle Field Service with the '+' symbol and all other non-digit characters are removed. For example, if you enter the phone number as [phone]_42, it is saved in Oracle Field Service as [phone]. Maximum field length is 240.",
            "title":"Customer Cell"
        },
        "customerNumber":{
            "type":"string",
            "description":"The account number of the customer. This field is used by integrations as a placeholder for the external identifier of the Account ID in the application. This parameter has no business significance in Oracle Field Service and can be left empty. Maximum field length is 40.",
            "title":"Customer Number"
        },
        "customerPhone":{
            "type":"string",
            "description":"The regular (land) phone number of the customer. The phone number is saved in Oracle Field Service with the '+' symbol and all other non-digit characters are removed. For example, if you enter the phone number as [phone]_42, it is saved in Oracle Field Service as [phone]. Maximum field length is 240.",
            "title":"Customer Phone"
        },
        "setPositionInRoute":{
            "$ref":"#/definitions/setPositionInRouteRequestField"
        },
        "setTravelTime":{
            "$ref":"#/definitions/setTravelTimeRequestField"
        },
        "requiredInventories":{
            "type":"array",
            "description":"List of inventories required by activity. Max 100 items.",
            "items":{
                "$ref":"#/definitions/requiredInventory"
            }
        },
        "resourcePreferences":{
            "type":"array",
            "description":"List of resource preferences for the activity. Max 100 items.",
            "items":{
                "$ref":"#/definitions/resourcePreference"
            }
        }
    },
    "description":"The properties of the new activity.",
    "type":"object"
}

Nested Schema : requiredInventories

Type: array

List of inventories required by activity. Max 100 items.

Show Source

• Array of: object Required Inventory
  Title: Required Inventory

  The array of required inventory item objects assigned to the specified activity.

{
    "type":"array",
    "description":"List of inventories required by activity. Max 100 items.",
    "items":{
        "$ref":"#/definitions/requiredInventory"
    }
}

Nested Schema : resourcePreferences

Type: array

List of resource preferences for the activity. Max 100 items.

Show Source

• Array of: object Resource Preference
  Title: Resource Preference

  The resource preference of an activity.

{
    "type":"array",
    "description":"List of resource preferences for the activity. Max 100 items.",
    "items":{
        "$ref":"#/definitions/resourcePreference"
    }
}

Nested Schema : Set Position in Route

Type: object

Title: Set Position in Route

The value of this element determines the position of the activity in the route. If this element is present then activity will be put to specified position in route. The parameter is optional, if it is absent then the value "position: byServiceWindow" is used.

Show Source

• activityId: integer
  Title: Activity ID

  The unique identifier of some pending ordered activity in the target route. It is used along with the 'afterActivity' value of the 'position' parameter so that to put one activity in the position after another.
• position(required): string
  Title: Position

  Allowed Values: [ "first", "last", "notOrdered", "byServiceWindow", "afterActivity" ]

  The position of the activity in the route.

{
    "properties":{
        "position":{
            "type":"string",
            "enum":[
                "first",
                "last",
                "notOrdered",
                "byServiceWindow",
                "afterActivity"
            ],
            "description":"The position of the activity in the route.",
            "title":"Position"
        },
        "activityId":{
            "type":"integer",
            "title":"Activity ID",
            "description":"The unique identifier of some pending ordered activity in the target route. It is used along with the 'afterActivity' value of the 'position' parameter so that to put one activity in the position after another."
        }
    },
    "required":[
        "position"
    ],
    "type":"object",
    "description":"The value of this element determines the position of the activity in the route. If this element is present then activity will be put to specified position in route. The parameter is optional, if it is absent then the value \"position: byServiceWindow\" is used.",
    "title":"Set Position in Route"
}

Nested Schema : Set Travel Time

Type: object

Title: Set Travel Time

The objects used to set the travel time of the activity. The travel time is set only if the specified previousActivity/previousActivityId is ordered before the activity for which the travel time is set.

Show Source

• position(required): string
  Title: Position

  Allowed Values: [ "first", "afterActivity" ]

  The expected position of the activity in a route.

  To adjust the travel time of an activity, specify the location from where the travel is starting. The location can be the start of the route or another activity. This information is used when activities are reordered or moved while performing a sequence of operations.

• previousActivity: object Previous Activity
  Title: Previous Activity

  The objects in this array are used instead of the 'previousActivityId' parameter to find activities when internal IDs cannot be used. For example, it is used for the bulkUpdate operation.

  The 'previousActivity' activity array contains two items: 'apptNumber' and 'customerNumber'. The parameter 'apptNumber' is mandatory. The parameter 'customerNumber' is only required when the 'bulkUpdate/identifyActivityBy' option is set to 'apptNumberPlusCustomerNumber'.

  The operation returns an error if the system is unable to find any activity using the specified 'apptNumber' and 'customerNumber' values.

• previousActivityId: integer
  Title: Previous Activity ID

  The identifier of a previous activity that requires travel time calculation.

  If an activity doesn't require traveling (for example, calling your manager), then the identifier of the activity cannot be used as the 'Travel previous activity ID'. In such case, it is assigned to an ID of a previous activity that required travel.

  This parameter is mandatory when the value of the parameter 'position' is 'afterActivity'.

  Note: The operation does not return any error if the adjustment cannot be made because the specified 'previousActivityId' doesn't correspond to a real-time activity. This can be detected by verifying the 'travelTime' value returned.

• source: string
  Title: Source

  Allowed Values: [ "manual", "external" ]

  The origin of the travel time data. The following are the allowed values:

  • manual - indicates that the travel time value is entered manually by a user.
  • external - indicates that the travel time value is estimated based on the statistics or street-level routing service results.
• travelTime(required): integer
  Title: Travel Time

  Minimum Value: 0

  Maximum Value: 65535

  The travel time for the specified activity.

{
    "properties":{
        "travelTime":{
            "type":"integer",
            "minimum":0,
            "maximum":65535,
            "description":"The travel time for the specified activity.",
            "title":"Travel Time"
        },
        "position":{
            "type":"string",
            "enum":[
                "first",
                "afterActivity"
            ],
            "description":"The expected position of the activity in a route.<p>To adjust the travel time of an activity, specify the location from where the travel is starting. The location can be the start of the route or another activity. This information is used when activities are reordered or moved while performing a sequence of operations.</p>",
            "title":"Position"
        },
        "source":{
            "type":"string",
            "enum":[
                "manual",
                "external"
            ],
            "title":"Source",
            "description":"The origin of the travel time data. The following are the allowed values:<ul><li>manual - indicates that the travel time value is entered manually by a user.</li><li>external - indicates that the travel time value is estimated based on the statistics or street-level routing service results.</li>"
        },
        "previousActivityId":{
            "type":"integer",
            "title":"Previous Activity ID",
            "description":"The identifier of a previous activity that requires travel time calculation.<p>If an activity doesn't require traveling (for example, calling your manager), then the identifier of the activity cannot be used as the 'Travel previous activity ID'. In such case, it is assigned to an ID of a previous activity that required travel.</p><p> This parameter is mandatory when the value of the parameter 'position' is 'afterActivity'.</p><p><b>Note:</b> The operation does not return any error if the adjustment cannot be made because the specified 'previousActivityId' doesn't correspond to a real-time activity. This can be detected by verifying the 'travelTime' value returned.</p>"
        },
        "previousActivity":{
            "type":"object",
            "title":"Previous Activity",
            "properties":{
                "apptNumber":{
                    "type":"string"
                },
                "customerNumber":{
                    "type":"string"
                }
            },
            "description":"The objects in this array are used instead of the 'previousActivityId' parameter to find activities when internal IDs cannot be used. For example, it is used for the bulkUpdate operation.<p>The 'previousActivity' activity array contains two items: 'apptNumber' and 'customerNumber'. The parameter 'apptNumber' is mandatory. The parameter 'customerNumber' is only required when the 'bulkUpdate/identifyActivityBy' option is set to 'apptNumberPlusCustomerNumber'.</p><p>The operation returns an error if the system is unable to find any activity using the specified 'apptNumber' and 'customerNumber' values.</p>"
        }
    },
    "required":[
        "position",
        "travelTime"
    ],
    "type":"object",
    "description":"The objects used to set the travel time of the activity. The travel time is set only if the specified previousActivity/previousActivityId is ordered before the activity for which the travel time is set.",
    "title":"Set Travel Time"
}

Nested Schema : Required Inventory

Type: object

Title: Required Inventory

The array of required inventory item objects assigned to the specified activity.

Show Source

• inventoryType(required): string
  Title: Required Inventory Type

  The required inventory type for the specified activity.
• model(required): string
  Title: Required Inventory Model

  The required inventory model for the specified activity.
• quantity(required): number
  Title: Required Inventory Quantity

  The required quantity of inventory for the specified activity.

{
    "type":"object",
    "required":[
        "inventoryType",
        "model",
        "quantity"
    ],
    "description":"The array of required inventory item objects assigned to the specified activity.",
    "properties":{
        "quantity":{
            "type":"number",
            "description":"The required quantity of inventory for the specified activity.",
            "title":"Required Inventory Quantity"
        },
        "inventoryType":{
            "type":"string",
            "description":"The required inventory type for the specified activity.",
            "title":"Required Inventory Type"
        },
        "model":{
            "type":"string",
            "description":"The required inventory model for the specified activity.",
            "title":"Required Inventory Model"
        }
    },
    "title":"Required Inventory"
}

Nested Schema : Resource Preference

Type: object

Title: Resource Preference

The resource preference of an activity.

Show Source

• preferenceType(required): string
  Title: Preference Type

  Allowed Values: [ "required", "preferred", "forbidden", "warehouse" ]

  The type of resource preference for the activity.

  • preferred - the resource is preferred while routing.
  • required - the activity can only be assigned to a required resource.
  • forbidden - the activity cannot be assigned to the specified resource.
  • warehouse - inventory may be installed from the specified resource
• resourceId: string
  Title: Resource ID

  The unique identifier of the resource in Oracle Field Service.

{
    "required":[
        "preferenceType"
    ],
    "properties":{
        "resourceId":{
            "type":"string",
            "description":"The unique identifier of the resource in Oracle Field Service. ",
            "title":"Resource ID"
        },
        "preferenceType":{
            "type":"string",
            "enum":[
                "required",
                "preferred",
                "forbidden",
                "warehouse"
            ],
            "description":"The type of resource preference for the activity.<ul><li>preferred - the resource is preferred while routing.</li><li>required - the activity can only be assigned to a required resource.</li><li>forbidden - the activity cannot be assigned to the specified resource.</li><li>warehouse - inventory may be installed from the specified resource</li></ul>",
            "title":"Preference Type"
        }
    },
    "description":"The resource preference of an activity.",
    "title":"Resource Preference",
    "type":"object"
}

Nested Schema : Previous Activity

Type: object

Title: Previous Activity

The objects in this array are used instead of the 'previousActivityId' parameter to find activities when internal IDs cannot be used. For example, it is used for the bulkUpdate operation.

The 'previousActivity' activity array contains two items: 'apptNumber' and 'customerNumber'. The parameter 'apptNumber' is mandatory. The parameter 'customerNumber' is only required when the 'bulkUpdate/identifyActivityBy' option is set to 'apptNumberPlusCustomerNumber'.

The operation returns an error if the system is unable to find any activity using the specified 'apptNumber' and 'customerNumber' values.

Show Source

• apptNumber: string
• customerNumber: string

{
    "type":"object",
    "title":"Previous Activity",
    "properties":{
        "apptNumber":{
            "type":"string"
        },
        "customerNumber":{
            "type":"string"
        }
    },
    "description":"The objects in this array are used instead of the 'previousActivityId' parameter to find activities when internal IDs cannot be used. For example, it is used for the bulkUpdate operation.<p>The 'previousActivity' activity array contains two items: 'apptNumber' and 'customerNumber'. The parameter 'apptNumber' is mandatory. The parameter 'customerNumber' is only required when the 'bulkUpdate/identifyActivityBy' option is set to 'apptNumberPlusCustomerNumber'.</p><p>The operation returns an error if the system is unable to find any activity using the specified 'apptNumber' and 'customerNumber' values.</p>"
}

Back to Top

Response

Supported Media Types

• application/json

200 Response

This section describes the 200 status response for this operation.

Body ()

Root Schema : Find Matching Resources for Urgent Assignment

Type: object

Title: Find Matching Resources for Urgent Assignment

The list of resources that match the criteria for urgent assignment.

Show Source

• items: array Resource Matches for Urgent Assignment
  Title: Resource Matches for Urgent Assignment

  The resources that match the specified request criteria for urgent assignment.

{
    "properties":{
        "items":{
            "items":{
                "description":"The record of the resource that has matched the specified criteria.",
                "title":"Resource Match",
                "properties":{
                    "nearestRoutingBucket":{
                        "type":"string",
                        "description":"The closest parent bucket that has the 'routing bucket' flag enabled.",
                        "title":"Nearest Routing Bucket"
                    },
                    "startTime":{
                        "type":"string",
                        "description":"The start time of the activity in YYYY-MM-DD HH:MM:SS format. The time is returned in UTC time zone.",
                        "title":"Start Time"
                    },
                    "estimatedAvailability":{
                        "type":"string",
                        "description":"The estimated time when the technician has completed the activity in YYYY-MM-DD HH:MM:SS format. The time is returned in UTC time zone.",
                        "title":"Start Time"
                    },
                    "longitude":{
                        "type":"string",
                        "description":"The last known longitude of the resource.",
                        "title":"Longitude"
                    },
                    "latitude":{
                        "type":"string",
                        "description":"The last known latitude of the resource.",
                        "title":"Latitude"
                    },
                    "resourceDetails":{
                        "allOf":[
                            {
                                "$ref":"#/definitions/resourceDetails"
                            }
                        ],
                        "properties":{
                            "resourceInternalId":{
                                "type":"integer",
                                "description":"The internal identifier of the resource in Oracle Field Service. This is a read-only field.",
                                "title":"Resource Internal ID"
                            }
                        },
                        "description":"The data structure that contains the resource information."
                    }
                },
                "type":"object"
            },
            "type":"array",
            "description":"The resources that match the specified request criteria for urgent assignment.",
            "title":"Resource Matches for Urgent Assignment"
        }
    },
    "title":"Find Matching Resources for Urgent Assignment",
    "description":"The list of resources that match the criteria for urgent assignment.",
    "type":"object"
}

Nested Schema : Resource Matches for Urgent Assignment

Type: array

Title: Resource Matches for Urgent Assignment

The resources that match the specified request criteria for urgent assignment.

Show Source

• Array of: object Resource Match
  Title: Resource Match

  The record of the resource that has matched the specified criteria.

{
    "items":{
        "description":"The record of the resource that has matched the specified criteria.",
        "title":"Resource Match",
        "properties":{
            "nearestRoutingBucket":{
                "type":"string",
                "description":"The closest parent bucket that has the 'routing bucket' flag enabled.",
                "title":"Nearest Routing Bucket"
            },
            "startTime":{
                "type":"string",
                "description":"The start time of the activity in YYYY-MM-DD HH:MM:SS format. The time is returned in UTC time zone.",
                "title":"Start Time"
            },
            "estimatedAvailability":{
                "type":"string",
                "description":"The estimated time when the technician has completed the activity in YYYY-MM-DD HH:MM:SS format. The time is returned in UTC time zone.",
                "title":"Start Time"
            },
            "longitude":{
                "type":"string",
                "description":"The last known longitude of the resource.",
                "title":"Longitude"
            },
            "latitude":{
                "type":"string",
                "description":"The last known latitude of the resource.",
                "title":"Latitude"
            },
            "resourceDetails":{
                "allOf":[
                    {
                        "$ref":"#/definitions/resourceDetails"
                    }
                ],
                "properties":{
                    "resourceInternalId":{
                        "type":"integer",
                        "description":"The internal identifier of the resource in Oracle Field Service. This is a read-only field.",
                        "title":"Resource Internal ID"
                    }
                },
                "description":"The data structure that contains the resource information."
            }
        },
        "type":"object"
    },
    "type":"array",
    "description":"The resources that match the specified request criteria for urgent assignment.",
    "title":"Resource Matches for Urgent Assignment"
}

Nested Schema : Resource Match

Type: object

Title: Resource Match

The record of the resource that has matched the specified criteria.

Show Source

• estimatedAvailability: string
  Title: Start Time

  The estimated time when the technician has completed the activity in YYYY-MM-DD HH:MM:SS format. The time is returned in UTC time zone.
• latitude: string
  Title: Latitude

  The last known latitude of the resource.
• longitude: string
  Title: Longitude

  The last known longitude of the resource.
• nearestRoutingBucket: string
  Title: Nearest Routing Bucket

  The closest parent bucket that has the 'routing bucket' flag enabled.
• resourceDetails: object resourceDetails
  The data structure that contains the resource information.
• startTime: string
  Title: Start Time

  The start time of the activity in YYYY-MM-DD HH:MM:SS format. The time is returned in UTC time zone.

{
    "description":"The record of the resource that has matched the specified criteria.",
    "title":"Resource Match",
    "properties":{
        "nearestRoutingBucket":{
            "type":"string",
            "description":"The closest parent bucket that has the 'routing bucket' flag enabled.",
            "title":"Nearest Routing Bucket"
        },
        "startTime":{
            "type":"string",
            "description":"The start time of the activity in YYYY-MM-DD HH:MM:SS format. The time is returned in UTC time zone.",
            "title":"Start Time"
        },
        "estimatedAvailability":{
            "type":"string",
            "description":"The estimated time when the technician has completed the activity in YYYY-MM-DD HH:MM:SS format. The time is returned in UTC time zone.",
            "title":"Start Time"
        },
        "longitude":{
            "type":"string",
            "description":"The last known longitude of the resource.",
            "title":"Longitude"
        },
        "latitude":{
            "type":"string",
            "description":"The last known latitude of the resource.",
            "title":"Latitude"
        },
        "resourceDetails":{
            "allOf":[
                {
                    "$ref":"#/definitions/resourceDetails"
                }
            ],
            "properties":{
                "resourceInternalId":{
                    "type":"integer",
                    "description":"The internal identifier of the resource in Oracle Field Service. This is a read-only field.",
                    "title":"Resource Internal ID"
                }
            },
            "description":"The data structure that contains the resource information."
        }
    },
    "type":"object"
}

Nested Schema : resourceDetails

Type: object

The data structure that contains the resource information.

Show Source

• resourceInternalId: integer
  Title: Resource Internal ID

  The internal identifier of the resource in Oracle Field Service. This is a read-only field.

{
    "allOf":[
        {
            "$ref":"#/definitions/resourceDetails"
        }
    ],
    "properties":{
        "resourceInternalId":{
            "type":"integer",
            "description":"The internal identifier of the resource in Oracle Field Service. This is a read-only field.",
            "title":"Resource Internal ID"
        }
    },
    "description":"The data structure that contains the resource information."
}

Match All

The data structure that contains the resource information.

Show Source

• object resourceDetails

{
    "allOf":[
        {
            "$ref":"#/definitions/resourceDetails"
        }
    ],
    "properties":{
        "resourceInternalId":{
            "type":"integer",
            "description":"The internal identifier of the resource in Oracle Field Service. This is a read-only field.",
            "title":"Resource Internal ID"
        }
    },
    "description":"The data structure that contains the resource information."
}

Nested Schema : resourceDetails

Type: object

Show Source

• name: string
  The name of the resource.
• resourceId: string
  The identifier of the resource in the external system. The identifier of the resource is always returned in resourceDetails array.
• resourceType: string
  The specified resource type of a resource.

{
    "type":"object",
    "properties":{
        "resourceId":{
            "type":"string",
            "description":"The identifier of the resource in the external system. The identifier of the resource is always returned in resourceDetails array."
        },
        "name":{
            "type":"string",
            "description":"The name of the resource."
        },
        "resourceType":{
            "type":"string",
            "description":"The specified resource type of a resource."
        }
    }
}

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 find resources for urgent activity assignments by submitting a POST request on the REST resource:

cURL command Example

curl -u "<CLIENT-ID>@<INSTANCE-NAME>:<CLIENT-SECRET>" \
    -X POST \
    --data-binary '{
        "activity": {
        "latitude": 28.6685,
        "longitude": -81.4181,
        "activityType": "urgent-outage",
        "language": "en-US",
        "timeZone": "America/New_York",
        "city": "Altamonte Springs",
        "postalCode": "12345"
    },
    "radius": 300000,
    "resourceFields": [
        "resourceId",
        "name"
    ],
    "parentResources": [
        "east-x02"
    ]
        }' \
'https://<instance_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/resources/custom-actions/findResourcesForUrgentAssignment'

Response Header Example

The following shows an example of the response header.

HTTP/1.1 200 OK
Server: nginx/1.6.3
Date: Wed, 16 Sep 2015 15:32:19 GMT
Content-Type: application/json; charset=utf-8
Connection: close
X-Powered-By: PHP/7.0.25

Response Body Example

The following shows an example of the response body in JSON format.

{
    "items": [
        {
            "longitude": 28.66,
            "latitude": -81.41,
            "nearestRoutingBucket": "ResourcesGVHYFDBDGP1",
            "startTime": "2018-01-31 14:10:00",
            "estimatedAvailability": "2018-01-31 14:40:00",
            "resourceDetails": {
                "resourceId": "rx0101",
                "name": "Jane Doe"
            }
        },
        {
            "longitude": 28.67,
            "latitude": -81.40,
            "nearestRoutingBucket": "ResourcesGVHYFDBDGP2",
            "startTime": "2018-01-31 14:20:33",
            "estimatedAvailability": "2018-01-31 14:50:00",
            "resourceDetails": {
                "resourceId": "rx0202",
                "name": "Jack Smith"
            }
        }
    ]
}

Back to Top