V11 SP8
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.

XML

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

Name Description Element Parent Element
clientName The name of the client. 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 iDataAgent is installed. 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.

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 True/False.

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 is 4 MB that can held 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 openVMSProperties

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 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>