Loading...

REST API - POST Client Properties

This operation updates the properties associated with a client.

Request

Syntax

Send the request using either the ID or the name:

  • ID

    POST <webservice>/Client/{clientId} HTTP/1.1
    Host: <host name>
    Accept: application/xml
    Authtoken: <authentication token>
    Content-type: application/xml

    <update_client_template.xml>

  • Name

    POST <webservice>/Client/byName(clientName='{clientName}') HTTP/1.1
    Host: <host name>
    Accept: application/xml
    Authtoken: <authentication token>
    Content-type: application/xml

    <update_client_template.xml>

where <webservice> is the root path used to route the API requests to the Web Server.

For more information, see Available Web Services for REST API.

Request Parameters

Name

Description

Required

clientId

The client ID for the client. If the client ID is not known, use the GET Client API to retrieve it.

Yes-for the request by ID

clientName

The client name of the client. If the client name is not known, use the GET Client API to retrieve it.

Yes-for the request by name

Request Headers

Name

Description

Host

The host name of the Web Server or Web Console used in the API request.

Accept

The format of the response. Valid values are: application/xml or application/json.

Authtoken

The authentication token received after successfully logging on. For details on receiving an authentication token, see Authentication.

Content-type

The media type contained in the request body.

Request Body

Download the update_client_template.xml file required for this request. The following table displays the parameters for the update_client_template file.

Parameter

Description

Element

Parent Element

clientName

The name of the client.

entity

association

displayName

The display name of the client, which can be different from the original client name.

entity

association

clientDescription

A general description of the client.

client

clientProperties

clientName

The name of the client.

clientEntity

client

commCellName

The name of the CommCell.

clientEntity

client

hostName

The long name of the client, for example, client.domain.company.com.

clientEntity

client

cvdPort

The TCP port number for the Communications Service (CVD).

client

clientProperties

evmgrcPort

The TCP port number for the Client Manager Service (ClMgrS).

Applies to upgraded clients or clients from previous Commvault versions.

client

clientProperties

installDirectory

The directory where the base software and/or agent is installed.

client

clientProperties

displayName

The display name of the client, which can be different from the original client name.

client

clientProperties

path

The directory where the job results reside.

jobResulsDir

client

userName

The name of the user.

userAccount

jobResulsDir

clientGroupName

The name of the client computer group.

clientGroups

clientProperties

AltCachePartitionForQSnap

The location of the alternate cache partition used for QSnap.

clientProps

clientProperties

AutoUpdateLocation

 

clientProps

clientProperties

CDRLogFileLocation

The location of the ContinuousDataReplicator (CDR) log files.

clientProps

clientProperties

CenteraResourceFilename

The file name for the Centera resource.

clientProps

clientProperties

CipherType

The cipher to use for data encryption.

Valid values are:

  • 3-DES
  • AES (Rijndael)
  • Blowfish
  • GOST
  • Serpent
  • TwoFish

clientProps

clientProperties

DirectMediaAccessFlag

The storage option for the data encryption key.

Valid values are:

  • Regular, for Via Media Password
  • ViaPassPhrase, for Via Pass Phrase
  • None, for No Access

clientProps

clientProperties

EnableCollectDelegateInfo

Valid values are True/False.

clientProps

clientProperties

EnableContentIndexing

The option to enable content indexing.

Valid values are True/False.

clientProps

clientProperties

EnableEncryption

The option to enable data encryption.

Valid values are True/False.

clientProps

clientProperties

encryptionSettings

The option to enable data encryption.

Valid values are:

  • USE_SPSETTINGS, to encrypt data according to the settings in the storage policy copy
  • ON_CLIENT, to set encryption on the client
  • OFF, to disable encryption

clientProps

clientProperties

EnableSnapBackups

The option to enable snap backups.

Valid values are True/False.

clientProps

clientProperties

EncryptKeyLength

The key length to use with the cipher in the CipherType parameter. For the valid key length for each cipher, see Data Encryption Algorithms.

clientProps

clientProperties

JobPriority

The option to set the job priority.

Valid values are 0 to 9.

clientProps

clientProperties

JobResultsDiskCapThreshold

The percentage of disk capacity that is reached before job results are pruned.

clientProps

clientProperties

JobResultsRetentionDays

The number of days to retain job results.

clientProps

clientProperties

JobResultsThresholdMB

The low space threshold in MB for the job results folder.

clientProps

clientProperties

OptimizeDataForSearch

The option to optimize data for searching.

Valid values are True/False.

clientProps

clientProperties

PathToExchangeMiningTool

The location of the Exchange Mining Tool.

clientProps

clientProperties

RestoreAccessFlag

The storage and accessibility of data encryption keys in the CommServe database.

Valid values are:

  • Regular, for storing keys scrambled in the CommServe database
  •  WithPassPhase, for storing keys locked with a user-supplied pass-phrase in the CommServe database

    If you are using "WithPassPhase," the DirectMediaAccessFlag parameter must be set to "ViaPassPhrase."

clientProps

clientProperties

RetryCountOnNetworkError

The number of times the Job Manager checks for network connectivity. Use this parameter when the EnableRetryOnNetworkError parameter is set to "true."

clientProps

clientProperties

RetryFrequencyInSecOnNetworkError

The interval (in seconds) the Job Manager checks for network connectivity. Use this parameter when the EnableRetryOnNetworkError parameter is set to "true."

clientProps

clientProperties

WebServer

The settings related to the Web Server.

clientProps

clientProperties

cacheSource

The source of the cache.

Valid values are:

  • COMMSERVE
  • UPDATEAGENT

clientProps

clientProperties

activityType

The client activities.

To perform an activity on a client, add the following elements to the <clientProperties>block in the XML file:

<clientProperties>
<clientProps>
<clientActivityControl>
<activityControlOptions activityType="1" enableActivityType="0"/>
<activityControlOptions activityType="2" enableActivityType="0"/>
</clientActivityControl>
</clientProps>
</clientProperties>

Valid values are:

  • 1, for backup
  • 2, for restore
  • 4, for auxiliary copy
  • 8, for disaster recovery backup
  • 16, archive pruning
  • 32, for media recycle
  • 64, for synthetic full
  • 28, all activity
  • 256, for schedule
  • 1024, for offline content indexing

activityControlOptions

clientActivityControl

TimeZoneName

The time zone to use when the Enable after a Delay option is used with an activity. Use this parameter when the enableAfterADelay parameter is set to "true."

Sample values:

  • (UTC) Coordinated Universal Time
  • (UTC-05:00) Eastern Time (US & Canada)

dateTime

activityControlOptions

timeValue

The date and time to use when the Enable after a Delay option is used with an activity. Use this parameter when the enableAfterADelay parameter is set to "true."

Sample values:

  • 2013-12-11 09:22:32
  • 2014-01-01 17:22:32

dateTime

activityControlOptions

enableActivityType

The option to enable or disable an activity for a client.

Valid values are:

  • 1
  • 0

activityControlOptions

clientActivityControl

enableAfterADelay

The option to enable an activity for a client on a date and time defined in the Enable Backup dialog box.

Valid values are True/False.

activityControlOptions

clientActivityControl

associationsOperationType

The operation to perform on the role, users, and user groups inside the <associations> block. The client, role, users, and user groups form a security association. To perform an operation on multiple security associations, add an <associations> block in the XML file for each security association:

<associations>
  <properties>
    <role>
      <roleName></roleName>
    </role>
  </properties>
  <userOrGroup>
    <userName></userName>
  </userOrGroup>
  <userOrGroup>
    <userGroupName></userGroupName>
  </userOrGroup>
</associations>

Valid values are:

  • ADD, to create a new security association between the client, the role, and users or user groups
  • OVERWRITE, to overwrite existing security associations with new security associations
  • DELETE, to delete one or more security associations

securityAssociations

clientProps

roleName

The name of the role operated on by the associationsOperationType parameter. The <associations> block must have exactly one role, for example:

<associations>
  <properties>
    <role>
      <roleName>Role3</roleName>
    </role>
  </properties>
...
...
</associations>

role

properties

userName

The name of the user operated on by the associationsOperationType parameter. To add multiple users to a security association, add the following elements in the XML file for each user:

<userOrGroup>
  <userName></userName>
</userOrGroup>

A mix of users and user groups can be a part of a security association, for example:

<userOrGroup>
  <userName>jdoe</userName>
</userOrGroup>
<userOrGroup>
  <userGroupName>support</userGroupName>
</userOrGroup>

userOrGroup

associations

userGroupName

The name of the user group operated on by the associationsOperationType parameter. To add multiple user groups to a security association, add the following elements in the XML file for each user:

<userOrGroup>
  <userGroupName></userGroupName>
</userOrGroup>

A mix of user groups and users can be a part of a security association, for example:

<userOrGroup>
  <userName>jdoe</userName>
</userOrGroup>
<userOrGroup>
  <userGroupName>support</userGroupName>
</userOrGroup>

userOrGroup

associations

externalGroupName

The name of the external user group operated on by the associationsOperationType parameter. Use this parameter with the providerDomainName parameter.

userOrGroup

associations

providerDomainName

The name of the domain that the external user group belongs to. Use this parameter with the externalGroupName parameter.

userOrGroup

associations

categoriesPermissionOperationType

The operation to perform on the client owner permissions in the permissionName parameter.

Valid values are:

  • ADD, to add a new permission to the client owner
  • OVERWRITE, to overwrite existing permissions
  • DELETE, to delete one or more permissions

categoryPermission

ownerAssociations

permissionName

The name of the client owner permission operated on by the categoriesPermissionOperationType parameter.

To work with multiple permissions, add the following elements in the XML file for each permission:

<categoriesPermissionList>
  <permissionName></permissionName>
</categoriesPermissionList>

For a list of valid values, see User Security Permissions and Permitted Actions.

categoriesPermissionList

categoryPermission

ownersOperationType

The operation to perform on the client owners in the userGroupName and userName parameters inside the <ownerAssociations> block.

Valid values are:

  • ADD, to add a new client owner to the client
  • OVERWRITE, to overwrite existing client owners
  • DELETE, to delete one or more client owners

ownerAssociations

securityAssociations

userGroupName

The name of the user group operated on by the ownersOperationType parameter. To add multiple user groups, add the following elements in the XML file for each user group:

<owners>
  <userGroupName></userGroupName>
</owners>

A mix of users and user groups can be added as client owners, for example:

<owners>
  <userName>jdoe</userName>
</owners>
<owners>
  <userGroupName>support</userGroupName>
</owners>

owners

ownerAssociations

userName

The name of the client owner operated on by the ownersOperationType parameter. To add multiple client owners, add the following elements in the XML file for each client owner:

<owners>
  <userName></userName>
</owners>

A mix of users and user groups can be added as client owners, for example:

<owners>
  <userName>jdoe</userName>
</owners>
<owners>
  <userGroupName>support</userGroupName>
</owners>

owners

ownerAssociations

cacheBufferSize

The option to set buffer size for the data that can be held to perform source side deduplication. The default buffer size of 4096 KB can hold the data of 32 signatures. The high latency deduplication database reply needs more data to cache to not interrupt the read operation. Use this option to increase the data-buffer cache.

deDuplicationProperties

clientProps

clientSideDeduplication

The option to enable Client Side Deduplication.

Valid values are:

  • USE_SPSETTINGS, to use storage policy settings
  • ON_CLIENT, to enable client side deduplication
  • OFF, to disable client side deduplication

deDuplicationProperties

clientProps

enableClientSideDiskCache

The option to enable a client side disk cache. Use this parameter when the clientSideDeduplication parameter is set to "ON_CLIENT."

Valid values are True/False.

deDuplicationProperties

clientProps

enableHighLatencyOptimization

The option to enable high latency optimization. Use this parameter when the enableClientSideDiskCache parameter is set to "true."

Valid values are True/False.

deDuplicationProperties

clientProps

enableVariableContentAlignment

The option to enable variable content alignment.

Valid values are True/False.

deDuplicationProperties

clientProps

maxCacheDb

The option to set the maximum size in megabytes for the database of deduplication database signature local cache.

Use this parameter when the enableClientSideDiskCache parameter is set to "true."

Valid values are:

  • 1024
  • 2048
  • 4096
  • 8192
  • 16384
  • 32768
  • 65536
  • 131072

deDuplicationProperties

clientProps

performClientSideDeduplication

The option to enable or disable source side deduplication.

Valid values are True/False.

deDuplicationProperties

clientProps

dlpEnableClientKeys

The option to unlock files before backups are performed and to allow users to open locked files without entering a pass-key.

dlpPropertise

clientProps

dlpMinFileAgeMins

The age in minutes of a document (created or modified) before it is locked during a DLP scan.

dlpPropertise

clientProps

dlpRmNow

The option to erase the files listed in the val parameter in the dlpRmFilters element. This action is irreversible.

Valid values are True/False.

dlpRMProperties

dlpPropertise

dlpRmOfflineDays

The number of days a client must be offline before files are erased.

dlpRMProperties

dlpPropertise

enableRmDLP

The option to enable the Secure Erase feature of Data Loss Prevention (DLP).

Valid values are True/False.

dlpRMProperties

dlpPropertise

val

The path to the content that will be deleted when Secure Erase is activated.

dlpRmContent

dlpRMProperties

val

The paths or file extensions that should not be deleted  when Secure Erase is activated, for example, *.exe.

dlpRmFilters

dlpRMProperties

dlpScanIntervalMins

The number of minutes the DLP scan waits between scans for new or unlocked content.

dlpPropertise

clientProps

dlpStolen

The option to mark the client as stolen.

Valid values are True/False.

dlpPropertise

clientProps

enableDLP

The option to enable Data Loss Prevention (DLP).

Valid values are True/False.

dlpPropertise

clientProps

val

The path to the content that should be locked when the DLP scan runs.

dlpContents

dlpPropertise

val

The paths or file extensions that should not be locked when the DLP scan runs, for example, *.dll.

dlpFilters

dlpPropertise

enableAccessControl

This option to enable access control.

Valid values are True/False.

clientProps

clientProperties

fileLevelAnalyticsLicense

Valid values are True/False.

clientProps

clientProperties

isWebServerInstalled

Indicates whether a web server is installed.

Valid values are True/False.

clientProps

clientProperties

overrideGlobalDesktopGuiProperties

Valid values are True/False.

clientProps

clientProperties

recallService

The complete address of the proxy service installed with the Web Console.

clientProps

clientProperties

SMTPAddressOfTheRMSSuperUser

The SMTP address of the RMS (Rights Management Services) super user.

rightManagementServiceProperties

clientProps

decryptRMSDocumentDuringContentIndexing

The option to decrypt an RMS (Rights Management Services) document during content indexing.

Valid values are True/False.

rightManagementServiceProperties

clientProps

userName

The name of the user.

rmsCredentials

rightManagementServiceProperties

smtpAddressOfRMSSuperUser

The SMTP address of the RMS (Rights Management Services) super user.

rightManagementServiceProperties

clientProps

enableOnlineSearch

The option to enable online searching.

Valid values are True/False.

spWebServerProperties

clientProps

spWebServerUserPassword

The user password for the SharePoint web server.

spWebServerProperties

clientProps

clientName

The name of the client.

webSearchServer

clientProps

hostName

The long name of the client, for example, client.domain.company.com.

webSearchServer

clientProps

webSearchServerForSuperSearch

The web server used for the search.

clientProps

clientProperties

webSearchServiceUrl

The URL for the web search.

clientProps

clientProperties

isJobThrottleEnabledAtCS

Enables job throttling at the CommServe level.

Valid values are 0/1.

jobThrottleSettings

clientProps

isJobThrottleEnabled

Enables job throttling at the client level. The isJobThrottleEnabledAtCS parameter must be enabled to turn job throttling on at the client level.

Valid values are 0/1.

jobThrottleSettings

clientProps

excludeImmidiateJobs

Exclude immediate jobs from being throttled. All application command line jobs and CommCell Console jobs run with the immediate option are counted as immediate jobs. The isJobThrottleEnabled parameter must be enabled before you configure job throttling settings.

Valid values are 0/1.

jobThrottleSettings

clientProps

dataThreshold

Limits the number of data backup jobs that run simultaneously. The isJobThrottleEnabled parameter must be enabled before you configure job throttling settings.

Valid values are 1 to 100.

jobThrottleSettings

clientProps

logThreshold

Limits the number of log backup jobs that run simultaneously.

The isJobThrottleEnabled parameter must be enabled before you configure job throttling settings.

Valid values are 1 to 100.

jobThrottleSettings

clientProps

configureClusterClient

The option to enable the cluster group configuration.

Valid values are True/False.

clusterClientProperties

clientProperties

showAllAgents

The option to show all agents.

Valid values are True/False.

clusterClientProperties

clientProperties

cvdPort

The TCP port number for the Communications Service (CVD).

openVMSProperties

pseudoClientInfo

userName

The name of the user.

userAccount

dopenVMSProperties

Response

Response Parameters

Parameter

Description

Element

errorCode

The possible error codes.

Valid values are:

  • 0, successful completion.
  • 2, a failure.
  • a specific error code.

response

warningCode

The possible warning codes.

Valid values are:

  • 0, successful completion.

response

Examples

Sample Request

This request updates the client description. The client description is in the clientDescription element.

POST <webservice>/Client/2 HTTP/1.1
Host: client.mydomain.com
Accept: application/xml
Authtoken: QSDK 38568012f4d1e8ee1841d283a47aa3ba78e124ea58354b5fc6
0f4dab8a63347d05cf5552484dafda3bfa4c5db84e580b1cb37bcf8e65b39f7f
8549a443e6f78a2c7be3f31b3d845e24776c835e498e8e883bb40c46bd15af4f
40ca94e823acedcdd4e9659e74b34a07a85c4586cd2ed914b6dce015874783ef7
68fda78183a4208930954a377f66eb56c8b92cexampl4s437a19317ca6ce7f323
3d5a01aca35dbad93468b833f2cf71010809006a937670adce711ca8be46638e8
Content-type: application/xml

<App_SetClientPropertiesRequest>
  <association>
    <entity>
      <clientName>client001</clientName>
    </entity>
  </association>
  <clientProperties>
    <client>
      <clientDescription>client-level description modified with rest api POST client</clientDescription>
    </client>
  </clientProperties>
</App_SetClientPropertiesRequest>

This request updates the security association for the client. The security association is the combination of the client in the clientName element plus the role, user, and user group in the securityAssociations block.

POST <webservice>/Client/2 HTTP/1.1
Host: client.mydomain.com
Accept: application/xml
Authtoken: QSDK 38568012f4d1e8ee1841d283a47aa3ba78e124ea58354b5fc6
0f4dab8a63347d05cf5552484dafda3bfa4c5db84e580b1cb37bcf8e65b39f7f
8549a443e6f78a2c7be3f31b3d845e24776c835e498e8e883bb40c46bd15af4f
40ca94e823acedcdd4e9659e74b34a07a85c4586cd2ed914b6dce015874783ef7
68fda78183a4208930954a377f66eb56c8b92cexampl4s437a19317ca6ce7f323
3d5a01aca35dbad93468b833f2cf71010809006a937670adce711ca8be46638e8
Content-type: application/xml

<App_SetClientPropertiesRequest>
  <association>
    <entity>
      <clientName>client001</clientName>
    </entity>
  </association>
  <clientProperties>
    <clientProps>
      <securityAssociations>
        <associationsOperationType>OVERWRITE</associationsOperationType>
        <associations>
          <properties>
            <role>
              <roleName>role003</roleName>
            </role>
          </properties>
          <userOrGroup>
            <userName>jsmith</userName>
          </userOrGroup>
          <userOrGroup>
            <userGroupName>support</userGroupName>
          </userOrGroup>
        </associations>
      </securityAssociations>
    </clientProps>
  </clientProperties>
</App_SetClientPropertiesRequest>

This request disables the backup activity on a client.

POST <webservice>/Client/byName(clientName='helios') HTTP/1.1
Host: client.mydomain.com
Accept: application/xml
Authtoken: QSDK 38568012f4d1e8ee1841d283a47aa3ba78e124ea58354b5fc6
0f4dab8a63347d05cf5552484dafda3bfa4c5db84e580b1cb37bcf8e65b39f7f
8549a443e6f78a2c7be3f31b3d845e24776c835e498e8e883bb40c46bd15af4f
40ca94e823acedcdd4e9659e74b34a07a85c4586cd2ed914b6dce015874783ef7
68fda78183a4208930954a377f66eb56c8b92cexampl4s437a19317ca6ce7f323
3d5a01aca35dbad93468b833f2cf71010809006a937670adce711ca8be46638e8
Content-type: application/xml
<App_SetClientPropertiesRequest>
<association>
<entity>
<clientName>helios</clientName>
</entity>
</association>
<clientProperties>
<clientProps>
<clientActivityControl>
<activityControlOptions activityType="1" enableActivityType="0"/>
</clientActivityControl>
</clientProps>
</clientProperties>
</App_SetClientPropertiesRequest>

This request updates the client owners and their permissions.

POST <webservice>/Client/byName(clientName='client001') HTTP/1.1
Host: client.mydomain.com
Accept: application/xml
Authtoken: QSDK 38568012f4d1e8ee1841d283a47aa3ba78e124ea58354b5fc6
0f4dab8a63347d05cf5552484dafda3bfa4c5db84e580b1cb37bcf8e65b39f7f
8549a443e6f78a2c7be3f31b3d845e24776c835e498e8e883bb40c46bd15af4f
40ca94e823acedcdd4e9659e74b34a07a85c4586cd2ed914b6dce015874783ef7
68fda78183a4208930954a377f66eb56c8b92cexampl4s437a19317ca6ce7f323
3d5a01aca35dbad93468b833f2cf71010809006a937670adce711ca8be46638e8
Content-type: application/xml

<App_SetClientPropertiesRequest>
  <association>
    <entity>
      <clientName>client001</clientName>
    </entity>
  </association>
  <clientProperties>
    <clientProps>
      <securityAssociations>
        <ownerAssociations>
          <categoryPermission>
            <categoriesPermissionOperationType>OVERWRITE</categoriesPermissionOperationType>
            <categoriesPermissionList>
            <permissionName>Data Protection Operations</permissionName>
            </categoriesPermissionList>
            <categoriesPermissionList>
            <permissionName>Job Management</permissionName>
            </categoriesPermissionList>
          </categoryPermission>
          <ownersOperationType>OVERWRITE</ownersOperationType>
          <owners>
            <userGroupName>support</userGroupName>
          </owners>
          <owners>
            <userGroupName>sales</userGroupName>
          </owners>
          <owners>
            <userName>jsmith</userName>
          </owners>
        </ownerAssociations>
      </securityAssociations>
    </clientProps>
  </clientProperties>
</App_SetClientPropertiesRequest>

Sample Response

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<App_SetClientPropertiesResponse>
  <response errorCode="0" warningCode="0"/>
</App_SetClientPropertiesResponse>

Last modified: 4/9/2021 6:22:26 AM