Custom Attributes Management

Get custom attribute definitions

This call gets all custom attribute definitions of the requested type, device or user, and the requested status, active or inactive.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Settings and Services Management

Role Description: View logs and events

HTTP method

GET

Request URI

api/v2/attributes/definitions

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

type

Required

Parameter Type: Query

Data Type: String

Type of attributes to return, device or user.

device

status

Parameter Type: Query

Data Type: String

Restricts the returned list to definitions of a specific status, active or inactive.

active

keyword

Parameter Type: Query

Data Type: String

Restricts returned list to definitions containing the specified keyword in name or description.

platform

Response fields

Field

Description

resultCount

The number of entries that are being returned.

totalCount

The total number of entries that the query matched.

messages

Container for messages.

    localizedMessage

Localized message with parameters resolved.

    messageKey

Message key.

    type

Message type.

results

Container for results

    modifiedAt

When modified.

    createdAt

When created.

    isFileTransferConfigAttribute

true or false. Indicates whether the attribute is part of an Android File Transfer configuration. For more information, see "Android File Transfer Configuration" in the Ivanti EPMM Device Management Guide for Android and Android Enterprise devices.

    description

Description of the custom attribute.

    name

Name of the custom attribute.

    dataType

Dta type of the custom attribute.

    status

Status of the custom attribute, ACTIVE or INACTIVE.

    type

Type of the custom attribute, DEVICE or USER.

    id

ID for the custome attribute.

Sample Request

curl -k -sS -u <userName>:<password> -XGET 'https://[Ivanti EPMM]/api/v2/attributes/
definitions?type=device&adminDeviceSpaceId=1'

Sample Responses

{

    "resultCount": 2,

    "totalCount": 2,

    "messages": [

        {

            "localizedMessage": "Attribute definitions successfully fetched.",

            "messageKey": "com.mobileiron.vsp.messages.custom.attributes.get.definitions.success",

            "type": "Info"

        }

    ],

    "results": [

        {

            "modifiedAt": 1463183668000,

            "createdAt": 1463181777000,

            "isFileTransferConfigAttribute": false,

            "description": "just testing",

            "name": "flag1",

            "dataType": "BOOLEAN",

            "status": "ACTIVE",

            "type": "DEVICE",

            "id": 21

        },

        {

            "modifiedAt": 1463176881000,

            "createdAt": 1463172337000,

            "description": "just testing",

            "name": "testAttr1",

            "dataType": "LONG",

            "status": "INACTIVE",

            "type": "DEVICE",

            "id": 6

        }

    ]

}

 

Get custom attribute definition

This call gets the custom attribute definition specified by the id parameter.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Settings and Services Management

Role Description: Manage custom attributes

HTTP method

GET

Request URI

api/v2/attributes/definitions/{id}

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

id

Required

Parameter Type: Request path

Data Type: String

ID of the custom attribute whose data to retrieve.

2

Response fields

Field

Description

resultCount

The number of entries that are being returned.

totalCount

The total number of entries that the query matched.

messages

Container for messages.

    localizedMessage

Localized message with parameters resolved.

    messageKey

Message key.

    type

Message type.

results

Container for results

    modifiedAt

When modified.

    createdAt

When created.

    description

Description of the custom attribute.

    name

Name of the custom attribute.

    dataType

Dta type of the custom attribute.

    status

Status of the custom attribute, ACTIVE or INACTIVE.

    type

Type of the custom attribute, DEVICE or USER.

    id

ID for the custome attribute.

Sample Request

curl -k -sS -u <userName>:<password> -XGET 'https://[Ivanti EPMM]/api/v2/attributes/
definitions/2

Sample Responses

{

    "resultCount": 1,

    "totalCount": 1,

    "messages": [

        {

            "localizedMessage": "Attribute definitions successfully fetched.",

            "messageKey": "com.mobileiron.vsp.messages.custom.attributes.get.definitions.success",

            "type": "Info"

        }

    ],

    "results": {

        "modifiedAt": 1462571401000,

        "createdAt": 1462571401000,

        "description": "this space for rent",

        "name": "stringAttr1",

        "dataType": "STRING",

        "status": "ACTIVE",

        "type": "USER",

        "id": 2

    }

}

Create custom attribute definition

This call creates a custom attribute definition. Note that you cannot create more than 300 custom attribute definitions.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Settings and Services Management

Role Description: Manage custom attributes

HTTP method

POST

Request URI

api/v2/attributes/definitions

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

description

Parameter Type: Request body

Data Type: String

Description of the custom attribute to create.

Platform custom attribute.

name

Required

Parameter Type: Request body

Data Type: String

Name of the custom attribute to create.

TestAttribute

dataType

Required

Parameter Type: Request body

Data Type: String

Data type of the custom attribute to create. Three possible types:

BOOLEAN

LONG

STRING

long

type

Required

Parameter Type: Request body

Data Type: String

Type of the custom attribute to create, device or user.

device

Response fields

Field

Description

messages

Container for messages.

    localizedMessage

Localized message with parameters resolved.

    messageKey

Message key.

    type

Message type.

results

ID of the newly created custom attribute.

Sample Request

curl -k -sS -u <userName>:<password> -H "Content-Type: application/json" --data '{

  "description": "still just testing",

  "name": "testAttr2",

  "dataType": "long",

  "type": "device"

}' -XPOST 'https://[Ivanti EPMM]/api/v2/attributes/definitions?adminDeviceSpaceId=1'

Sample Responses

{

    "messages": [

        {

            "localizedMessage": "Attribute definition created successfully.",

            "messageKey": "com.mobileiron.vsp.messages.custom.attributes.create.definition.success",

            "type": "Info"

        }

    ],

    "results": 23

}

Update custom attribute definition

This call updates a custom attribute definition. You can update the description and status fields.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Settings and Services Management

Role Description: Manage custom attributes

HTTP method

PUT

Request URI

api/v2/attributes/definitions/{id}

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

id

ID of the custom attribute definition to update.

2

description

Parameter Type: Request body

Data Type: String

Updated description of the custom attribute.

Platform costum attribute.

status

Parameter Type: Request body

Data Type: String

Updated status of the custom attribute, active or inactive.

TestAttribute

Response fields

Field

Description

messages

Container for messages.

    localizedMessage

Localized message with parameters resolved.

    messageKey

Message key.

    type

Message type.

Sample Request

curl -k -sS -u <userName>:<password> -H "Content-Type: application/json" --data '{

  "description": "new description"

}' -XPUT 'https://[Ivanti EPMM]/api/v2/attributes/definitions/2?adminDeviceSpaceId=1'

Sample Responses

{

  "messages": [

    {

      "localizedMessage": "Attribute definition updated successfully.",

      "messageKey": "com.mobileiron.vsp.messages.custom.attributes.update.definition.success",

      "type": "Info"

    }

  ]

}

Get custom attributes for a device

This call gets all custom attribute definitions for the device corresponding to the value you send with the uuid parameter.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Device Management

Role Description: View dashboard, device page, device details

HTTP method

GET

Request URI

api/v2/attributes/device/{uuid}

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

uuid

Required

Parameter Type: Request path

Data Type: String

uuid of the device whose custom attributes to retrieve.

5f1db255-8d3d-4943-8bab-d556cacce855

Response fields

Field

Description

messages

Container for messages.

    localizedMessage

Localized message with parameters resolved.

    messageKey

Message key.

    type

Message type.

results

Container for results

    custom attribute name

Name of custom value attribute and corresponding value.

 

...

Sample Request

curl -k -sS -u <userName>:<password> -XGET 'https://[Ivanti EPMM]/api/v2/attributes/device/5f1db255-8d3d-4943-8bab-d556cacce855?adminDeviceSpaceId=1'

Sample Responses

{

    "messages": [

        {

            "localizedMessage": "Attribute values successfully fetched.",

            "messageKey": "com.mobileiron.vsp.messages.custom.attributes.get.values.success",

            "type": "Info"

        }

    ],

    "results": {

        "devBool1": "true",

        "devLong1": "42"

    }

}

Set device custom attributes

This call sets device custom attributes.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: Device Management

Role Description: Edit custom device attribute values

HTTP method

POST

Request URI

api/v2/attributes/device

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

uuids

Required

Parameter Type: Request body

Data Type: String

uuids of the devices whose custom attributes to set.

"136da21e-9e95-4ea2-8b51-343297c58d8b", "ada0e9cd-ca15-49f6-98a8-3d304b83809f"

attributes

Required

Parameter Type: Request body

Data Type: String

key-value pairs of the custom attributes to set and the desired values. Null or empty string ("") passed in as the value will remove any existing attribute value.

{ "flag1": "true", "flag2" : "false" }

Response fields

Field

Description

messages

Container for messages.

    localizedMessage

Localized message with parameters resolved.

    messageKey

Message key.

    type

Message type.

results

Container for results.

    deleteCount

How many values deleted as a result of this call.

    assignCount

How many values assigned as a result of this call.

    invalidUuids

List of invalid uuids.

Sample Request

curl -k -sS -u <userName>:<password> -H "Content-Type: application/json" --data '{

  "uuids": ["136da21e-9e95-4ea2-8b51-343297c58d8b", "ada0e9cd-ca15-49f6-98a8-3d304b83809f"],

  "attributes": { "flag1": "true", "flag2" : "false" }

}' -XPOST 'https://[Ivanti EPMM]/api/v2/attributes/device?adminDeviceSpaceId=1'

Sample Responses

{

    "messages": [

        {

            "localizedMessage": "Attribute values set successfully.",

            "messageKey": "com.mobileiron.vsp.messages.custom.attributes.set.values.success",

            "type": "Info"

        }

    ],

    "results": {

        "deleteCount": 0,

        "assignCount": 4,

        "invalidUuids": [ ]

    }

}

Get custom attributes for a user

This call gets all custom attribute definitions for the user corresponding to the value you send with the uuid parameter.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: User Management

Role Description: View user

HTTP method

GET

Request URI

api/v2/attributes/user/{uuid}

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

uuid

Required

Parameter Type: Request path

Data Type: String

uuid of the user whose custom attributes to retrieve.

5f1db255-8d3d-4943-8bab-d556cacce855

Response fields

Field

Description

messages

Container for messages.

    localizedMessage

Localized message with parameters resolved.

    messageKey

Message key.

    type

Message type.

results

Container for results

    custom attribute name

Name of custom value attribute and corresponding value.

 

...

Sample Request

curl -k -sS -u <userName>:<password> -XGET 'https://[Ivanti EPMM]/api/v2/attributes/user/a5eb8acb-5fad-4b59-b2bf-b98d04fc61c5?adminDeviceSpaceId=1'

Sample Responses

{

    "messages": [

        {

            "localizedMessage": "Attribute values successfully fetched.",

            "messageKey": "com.mobileiron.vsp.messages.custom.attributes.get.values.success",

            "type": "Info"

        }

    ],

    "results": {

        "userString1": "Woof!",

        "userLong1": "42"

    }

}

Set user custom attributes

This call sets user custom attributes.

Required Role

See Authentication for complete details on ensuring that the credentials you use for basic authentication belong to a user with the necessary role for this API call.

 

Required Role

Category: User Management

Role Description: Edit custom user attribute values

HTTP method

POST

Request URI

api/v2/attributes/user

Request parameters

Parameter

Description

Sample Value

adminDeviceSpaceId

Required

Parameter Type: Query

Data Type: Number

Device space ID of the administrator.

1

uuids

Required

Parameter Type: Request body

Data Type: String

uuids of the users whose custom attributes to set.

"c9d3a454-c1b9-4922-a381-932823d0c0e5", "28df8c43-20e0-44f3-9771-d526cc854e33", "a5eb8acb-5fad-4b59-b2bf-b98d04fc61c5"

attributes

Required

Parameter Type: Request body

Data Type: String

key-value pairs of the custom attributes to set and the desired values. Null or empty string ("") passed in as the value will remove any existing attribute value.

"userString1": "Woof!", "userLong1" : ""

Response fields

Field

Description

messages

Container for messages.

    localizedMessage

Localized message with parameters resolved.

    messageKey

Message key.

    type

Message type.

results

Container for results.

    deleteCount

How many values deleted as a result of this call.

    assignCount

How many values assigned as a result of this call.

    invalidUuids

List of invalid uuids.

Sample Request

curl -k -sS -u <userName>:<password> -H "Content-Type: application/json" --data '{

  "uuids": ["c9d3a454-c1b9-4922-a381-932823d0c0e5", "28df8c43-20e0-44f3-9771-d526cc854e33", "a5eb8acb-5fad-4b59-b2bf-b98d04fc61c5"],

  "attributes": { "userString1": "Woof!", "userLong1" : "" }

}' -XPOST 'https://[Ivanti EPMM]/api/v2/attributes/user?adminDeviceSpaceId=1'

Sample Responses

{

    "messages": [

        {

            "localizedMessage": "Attribute values set successfully.",

            "messageKey": "com.mobileiron.vsp.messages.custom.attributes.set.values.success",

            "type": "Info"

        }

    ],

    "results": {

        "deleteCount": 3,

        "assignCount": 3,

        "invalidUuids": [ ]

    }

}