REST API for Oracle Field Service Cloud Service

Get users

get

/rest/ofscCore/v1/users

This operation returns the list of users.

The visibility rules are based on the application's configuration parameter "Allow access only to certain resources", which allows to restrict the access by a list of resources. The function will only return users that associated with resources visible for the application which makes the request. For example if a requesting application has the access to the top level resource then all the users in the system are visible. If an application is configured with some resource(s) in the list "Allow access only to certain resources", then the visible users are only the users that associated with allowed resource(s) and the resources below in the resource hierarchy.

Request

Query Parameters

limit: integer

The number of items to be returned in the response. The minimum value that can be specified is 1 and the maximum value that can be specified is 100. If the specified value is greater than 100, zero, or if no value is specified, then it defaults to 100.
offset: integer

The record number from which the retrieval starts. The default value is zero. If no value is specified, then it defaults to zero. The value zero indicates that the retrieval will start from the beginning of the collection.

Response

Supported Media Types

application/json

200 Response

This section describes the 200 status response for this operation.

Root Schema : Users

Type: object

Title: Users

The collection of users.

Show Source

items: array Items

Title: Items

An array of objects containing the user account details.
limit: integer

Title: Limit

The limit value specified in the request. If the value is not specified in the request or if the specified value is not accepted, then it defaults to 100.
offset: integer

Title: Offset

The offset value specified in the request.
totalResults: integer

Title: Total Results

The total number of users.

{
    "title":"Users",
    "type":"object",
    "properties":{
        "totalResults":{
            "type":"integer",
            "description":"The total number of users.",
            "title":"Total Results"
        },
        "limit":{
            "type":"integer",
            "description":"The limit value specified in the request. If the value is not specified in the request or if the specified value is not accepted, then it defaults to 100.",
            "title":"Limit"
        },
        "offset":{
            "type":"integer",
            "description":"The offset value specified in the request.",
            "title":"Offset"
        },
        "items":{
            "items":{
                "$ref":"#/definitions/userGet"
            },
            "type":"array",
            "description":"An array of objects containing the user account details.",
            "title":"Items"
        }
    },
    "description":"The collection of users."
}

Nested Schema : Items

Type: array

Title: Items

An array of objects containing the user account details.

Show Source

Array of: object User

Title: User

The details of the user account.

{
    "items":{
        "$ref":"#/definitions/userGet"
    },
    "type":"array",
    "description":"An array of objects containing the user account details.",
    "title":"Items"
}

Nested Schema : User

Type: object

Title: User

The details of the user account.

Show Source

avatar: object Avatar

Title: Avatar

The profile picture of the user.
blockedUntilTime: string

Title: Blocked Until Time

The time until the account is blocked.
createdTime: string

Title: Created Time

The date and time when the user account is created.
dateFormat: string

Title: Date Format

The date format of the user account. Allowed Values: ["dd/mm/yy", "mm/dd/yy","dd.mm.yy","yyyy/mm/dd"].
language(required): string

Title: Language

The preferred language of the user. This field accepts the language codes listed on: Supported Language Codes.
lastLoginTime: string

Title: Last Login Time

The date and time when the user logged in to the account.
lastPasswordChangeTime: string

Title: Last Password Change Time

The date and time when the password was changed.
lastUpdatedTime: string

Title: Last Updated Time

The date and time when the user account was updated. This field is not updated if a custom property or the profile picture of the user is changed. This field is only updated when one of the built-in properties is changed.
login: string

Title: Login

The unique identifier of the user account in Oracle Field Service.
loginAttempts: integer

Title: Login Attempts

The number of unsuccessful login attempts.
longDateFormat: string

Title: Long Date Format

The long date format of the user account.
mainResourceId: string

Title: Main Resource ID

The unique identifier of the main resource of the user account. This field is only set for resources that represent field service personnel. It is not set for groups and routing buckets.
This field is not returned in the response if empty strings are passed in the request.
name(required): string

Title: Name

The full name of the user.
organizationalUnit: string

Title: Organizational Unit

The identifier of the organization unit where the user works. The value of this field can be the ID of a resource with the role as 'bucket' or 'organization unit'.
passwordTemporary: boolean

Title: Temporary Password

The temporary password of the user account. If the temporary password is set, then the user is prompted to change password on the next login.
resources(required): array Resources

Title: Resources

Minimum Number of Items: 1

Unique Items Required: true

The list of resources assigned to the user account. These resources along with their children are visible to the user. This list does not incIude the resources whose resource ID values are empty.
selfAssignment: boolean

Title: Self Assignment

Indicates whether the users can assign activities to themselves.
status: string

Title: Status

Allowed Values: [ "active", "inactive" ]

The status of the user account.
timeFormat: string

Title: Time Format

The time format of the user account. Allowed Values: [ "12-hour", "24-hour" ].
timeZone(required): string

Title: Time Zone

The name of the user's time zone.
This field 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 IANA names are specified.
For a list of supported time zones, see Supported Time Zones.
timeZoneDiff: integer

Title: Time Zone Diff

The difference between UTC and the user's local time, displayed in minutes. For example, -180 means that the user's time is 3 hours behind UTC.
This is a read-only field.
timeZoneIANA: string

Title: Time Zone IANA Name

The IANA name of the user's time zone (for example, America/New_York). For the list of IANA time zone names, see IANA Time Zones
This is a read-only field and is only returned in responses.
userType(required): string

Title: User Type

The type of the user account. The access controls of the user account are defined based on the user type.
weekStart: string

Title: Week Start

Allowed Values: [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "default" ]

The day on which the week starts for the user account.

{
    "properties":{
        "blockedUntilTime":{
            "type":"string",
            "description":"The time until the account is blocked.",
            "title":"Blocked Until Time"
        },
        "timeZone":{
            "type":"string",
            "description":"The name of the user's time zone. <p>This field 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 IANA names are specified.<p>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"
        },
        "timeZoneIANA":{
            "type":"string",
            "title":"Time Zone IANA Name",
            "description":"The IANA name of the user's time zone (for example, America/New_York). For the list of IANA time zone names, see <a href=https://www.iana.org/time-zones>IANA Time Zones</a><p>This is a read-only field and is only returned in responses.</p>"
        },
        "lastUpdatedTime":{
            "type":"string",
            "description":"The date and time when the user account was updated. This field is not updated if a custom property or the profile picture of the user is changed. This field is only updated when one of the built-in properties is changed.",
            "title":"Last Updated Time"
        },
        "weekStart":{
            "type":"string",
            "enum":[
                "sunday",
                "monday",
                "tuesday",
                "wednesday",
                "thursday",
                "friday",
                "saturday",
                "default"
            ],
            "description":"The day on which the week starts for the user account.",
            "title":"Week Start"
        },
        "name":{
            "type":"string",
            "description":"The full name of the user.",
            "title":"Name"
        },
        "lastLoginTime":{
            "type":"string",
            "description":"The date and time when the user logged in to the account.",
            "title":"Last Login Time"
        },
        "passwordTemporary":{
            "type":"boolean",
            "description":"The temporary password of the user account. If the temporary password is set, then the user is prompted to change password on the next login.",
            "title":"Temporary Password"
        },
        "loginAttempts":{
            "type":"integer",
            "description":"The number of unsuccessful login attempts.",
            "title":"Login Attempts"
        },
        "login":{
            "type":"string",
            "description":"The unique identifier of the user account in Oracle Field Service.",
            "title":"Login"
        },
        "lastPasswordChangeTime":{
            "type":"string",
            "description":"The date and time when the password was changed.",
            "title":"Last Password Change Time"
        },
        "longDateFormat":{
            "type":"string",
            "description":"The long date format of the user account.",
            "title":"Long Date Format"
        },
        "selfAssignment":{
            "type":"boolean",
            "description":"Indicates whether the users can assign activities to themselves.",
            "title":"Self Assignment"
        },
        "dateFormat":{
            "type":"string",
            "description":"The date format of the user account. Allowed Values: [\"dd/mm/yy\", \"mm/dd/yy\",\"dd.mm.yy\",\"yyyy/mm/dd\"].",
            "title":"Date Format"
        },
        "createdTime":{
            "type":"string",
            "description":"The date and time when the user account is created.",
            "title":"Created Time"
        },
        "mainResourceId":{
            "type":"string",
            "description":"The unique identifier of the main resource of the user account. This field is only set for resources that represent field service personnel. It is not set for groups and routing buckets.<p>This field is not returned in the response if empty strings are passed in the request.</p>",
            "title":"Main Resource ID"
        },
        "organizationalUnit":{
            "type":"string",
            "description":"The identifier of the organization unit where the user works. The value of this field can be the ID of a resource with the role as 'bucket' or 'organization unit'.",
            "title":"Organizational Unit"
        },
        "status":{
            "type":"string",
            "enum":[
                "active",
                "inactive"
            ],
            "description":"The status of the user account.",
            "title":"Status"
        },
        "language":{
            "type":"string",
            "description":"The preferred language of the user. This field accepts the language codes listed on: <a href=\"OFSC_Supported_Language_Codes.html\">Supported Language Codes</a>.",
            "title":"Language"
        },
        "avatar":{
            "properties":{
                "links":{
                    "type":"array",
                    "items":{
                        "properties":{
                            "rel":{
                                "type":"string"
                            },
                            "href":{
                                "type":"string"
                            },
                            "mediaType":{
                                "type":"string"
                            }
                        },
                        "required":[
                            "rel",
                            "href"
                        ]
                    }
                }
            },
            "type":"object",
            "description":"The profile picture of the user.",
            "title":"Avatar"
        },
        "resources":{
            "items":{
                "type":"string"
            },
            "type":"array",
            "uniqueItems":true,
            "minItems":1,
            "description":"The list of resources assigned to the user account. These resources along with their children are visible to the user. This list does not incIude the resources whose resource ID values are empty. ",
            "title":"Resources"
        },
        "timeFormat":{
            "type":"string",
            "description":"The time format of the user account. Allowed Values: [ \"12-hour\", \"24-hour\" ].",
            "title":"Time Format"
        },
        "userType":{
            "type":"string",
            "description":"The type of the user account. The access controls of the user account are defined based on the user type.",
            "title":"User Type"
        },
        "timeZoneDiff":{
            "type":"integer",
            "description":"The difference between UTC and the user's local time, displayed in minutes. For example, -180 means that the user's time is 3 hours behind UTC.<p>This is a read-only field.</p>",
            "title":"Time Zone Diff"
        }
    },
    "description":"The details of the user account.",
    "type":"object",
    "title":"User",
    "required":[
        "resources",
        "name",
        "language",
        "timeZone",
        "userType"
    ]
}

Nested Schema : Avatar

Type: object

Title: Avatar

The profile picture of the user.

Show Source

links: array links

{
    "properties":{
        "links":{
            "type":"array",
            "items":{
                "properties":{
                    "rel":{
                        "type":"string"
                    },
                    "href":{
                        "type":"string"
                    },
                    "mediaType":{
                        "type":"string"
                    }
                },
                "required":[
                    "rel",
                    "href"
                ]
            }
        }
    },
    "type":"object",
    "description":"The profile picture of the user.",
    "title":"Avatar"
}

Nested Schema : Resources

Type: array

Title: Resources

Minimum Number of Items: 1

Unique Items Required: true

The list of resources assigned to the user account. These resources along with their children are visible to the user. This list does not incIude the resources whose resource ID values are empty.

Show Source

Array of: string

{
    "items":{
        "type":"string"
    },
    "type":"array",
    "uniqueItems":true,
    "minItems":1,
    "description":"The list of resources assigned to the user account. These resources along with their children are visible to the user. This list does not incIude the resources whose resource ID values are empty. ",
    "title":"Resources"
}

Nested Schema : links

Type: array

Show Source

Array of: object items

{
    "type":"array",
    "items":{
        "properties":{
            "rel":{
                "type":"string"
            },
            "href":{
                "type":"string"
            },
            "mediaType":{
                "type":"string"
            }
        },
        "required":[
            "rel",
            "href"
        ]
    }
}

Nested Schema : items

Type: object

Show Source

href(required): string
mediaType: string
rel(required): string

{
    "properties":{
        "rel":{
            "type":"string"
        },
        "href":{
            "type":"string"
        },
        "mediaType":{
            "type":"string"
        }
    },
    "required":[
        "rel",
        "href"
    ]
}

Default Response

This section describes the default error response for this operation.

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"
    ]
}

Examples

The following example shows how to get users by submitting a GET request on the REST resource.

Example of Request Header

The following shows an example of the request header.

GET /rest/ofscCore/v1/users/?limit=5&offset=2 HTTP/1.0
Authorization: Basic c29hcEBwZXRyb2xpYXNoZXZ5Y2gucmVzdDox
Host: etadev1f
Accept: */*

Example of Response Header

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

Example of Response Body

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

{
    "totalResults": 58,
    "limit": 5,
    "offset": 2,
    "items": [
        {
            "resources": [
                "22"
            ],
            "collaborationGroups": {
              "links": [
                {
                  "rel": "canonical",
                  "href": "https://etadev1f/rest/ofscCore/v1/users/manager/collaborationGroups"
                }
              ]
            },
            "name": "Manager",
            "status": "active",
            "login": "manager",
            "language": "en",
            "dateFormat": 12,
            "longDateFormat": 16,
            "timeFormat": 14,
            "weekStart": "default",
            "timeZoneDiff": -300,
            "timeZone": "Eastern",
            "createdTime": "2006-02-03 09:20:08",
            "lastUpdatedTime": "2013-08-27 13:05:08",
            "lastLoginTime": "2013-08-27 13:05:08",
            "lastPasswordChangeTime": "2012-07-18 17:23:00",
            "userType": "Manager",
            "inventories": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/inventories"
                    }
                ]
            },
            "users": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/users"
                    }
                ]
            },
            "serviceRequests": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/serviceRequests"
                    }
                ]
            },
            "workZones": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/workZones"
                    }
                ]
            },
            "workSkills": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/workSkills"
                    }
                ]
            },
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://etadev1f/rest/ofscCore/v1/resources"
                },
                {
                    "rel": "describedby",
                    "href": "https://etadev1f/rest/ofscCore/v1/metadata-catalog/resources"
                }
            ]
        },
        {
            "resources": [
                "22"
            ],
            "collaborationGroups": {
              "links": [
                {
                  "rel": "canonical",
                  "href": "https://etadev1f/rest/ofscCore/v1/users/root/collaborationGroups"
                }
              ]
            },
            "name": "Administrator",
            "status": "inactive",
            "login": "root",
            "language": "en",
            "dateFormat": 12,
            "longDateFormat": 16,
            "timeFormat": 14,
            "weekStart": "default",
            "timeZoneDiff": -300,
            "timeZone": "Eastern",
            "createdTime": "2006-02-03 09:20:08",
            "lastUpdatedTime": "2013-04-11 13:54:47",
            "lastLoginTime": "2011-08-15 14:38:26",
            "lastPasswordChangeTime": "2006-04-27 15:48:15",
            "userType": "UT16_DISPLAY_PROFILE",
            "inventories": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/inventories"
                    }
                ]
            },
            "users": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/users"
                    }
                ]
            },
            "serviceRequests": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/serviceRequests"
                    }
                ]
            },
            "workZones": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/workZones"
                    }
                ]
            },
            "workSkills": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/workSkills"
                    }
                ]
            },
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://etadev1f/rest/ofscCore/v1/resources"
                },
                {
                    "rel": "describedby",
                    "href": "https://etadev1f/rest/ofscCore/v1/metadata-catalog/resources"
                }
            ]
        },
        {
            "resources": [
                "routing"
            ],
            "collaborationGroups": {
              "links": [
                {
                  "rel": "canonical",
                  "href": "https://etadev1f/rest/ofscCore/v1/users/CSR/collaborationGroups"
                }
              ]
            },
            "name": "CSR",
            "status": "active",
            "login": "CSR",
            "language": "en",
            "dateFormat": 12,
            "longDateFormat": 16,
            "timeFormat": 14,
            "weekStart": "default",
            "timeZoneDiff": -300,
            "timeZone": "Eastern",
            "createdTime": "2006-08-16 09:56:21",
            "lastUpdatedTime": "2013-04-11 13:54:47",
            "lastLoginTime": "2012-07-03 11:49:03",
            "lastPasswordChangeTime": "2012-03-01 10:04:54",
            "userType": "CSR",
            "inventories": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/inventories"
                    }
                ]
            },
            "users": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/users"
                    }
                ]
            },
            "serviceRequests": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/serviceRequests"
                    }
                ]
            },
            "workZones": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/workZones"
                    }
                ]
            },
            "workSkills": {
                "links": [
                    {
                        "rel": "canonical",
                        "href": "https://etadev1f/rest/ofscCore/v1/resources/workSkills"
                    }
                ]
            },
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://etadev1f/rest/ofscCore/v1/resources"
                },
                {
                    "rel": "describedby",
                    "href": "https://etadev1f/rest/ofscCore/v1/metadata-catalog/resources"
                }
            ]
        },
        ...
}            
}