Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

Data types

Many of the data types that describe HCP management API resources and properties are named, unordered sets of properties. When you create a resource, some properties for the applicable data type are required and some are optional. You need to specify a value for each required property. If you omit an optional property, HCP supplies a default value for it.

When you modify a resource, all properties for the applicable data type are optional. If you omit a property, the current value of the property remains unchanged.

When you create or modify a resource, HCP returns an error if the request body includes:

  • Properties that are not valid for the resource
  • Properties that are not valid for the request type
  • Properties whose values cannot be set with the user account used for the request
Note If a tenant has granted system-level users administrative access to itself, actions that can be performed with a tenant-level user account can also be performed with a system-level user account that includes the applicable roles.

Some resources also have required or optional query parameters.

Common property values

These types of values, among others, are common to multiple HCP management API resources or properties.

Passwords

User accounts have a password property. When creating or modifying a user account, the password is specified by the password query parameter.

When you create a tenant, you have the option of creating an initial user account for that tenant. In this case, you use query parameters, including the password parameter, to define that account.

To reset the passwords for all locally authenticated user accounts with the security role, you specify the new password in the resetPasswords query parameter.

When you enable WebDAV basic authentication, you need to specify a username and password. In this case, you use the webdavBasicAuthPassword property of the httpProtocol data type to specify the password.

Passwords can be up to 64 characters long, are case sensitive, and can contain any valid UTF-8 characters, including white space. To be valid, a password must include at least one character from two of these three groups: alphabetic, numeric, and other.

The minimum password length is configurable. To set the minimum password length, you use the minimumPasswordLength property of the consoleSecurity data type.

Descriptions

Namespaces, namespace defaults, retention classes, user accounts, replication links, and erasure coding topologies all have a description property. Tenants have two properties for descriptions — systemVisibleDescription and tenantVisibleDescription.

All descriptions can be up to 1,024 characters long and can contain any valid UTF-8 characters, including white space.

All description properties are optional. If you omit this property when you create a namespace, the description defaults to the description specified by the namespace defaults for the tenant. For other resources, the default on creation is no description.

Boolean values

For properties that take a Boolean value, valid values are:

  • true, t, or 1 (one)
  • false, f, or 0 (zero)

These values are case sensitive.

Invalid values are interpreted as false.

Permission lists

These resources and properties have values that are lists of permissions:

  • The permissions resource for tenants (specifies the permissions in the data access permission mask for a tenant)
  • The permissions resource for namespaces (specifies the permissions in the data access permission mask for a namespace)
  • The permissions property of the namespacePermission data type (used in the specification of the data access permissions for a user or group account)
  • The authMinimumPermissions and authAndAnonymousMinimum-Permissions properties of the namespaces data type

The permissions that can be included in a list differ for the various resources and properties. However, in each case:

  • In XML, the element that identifies each permission is permission. For example:
    <permissions>
        <permission>READ</permission>
        <permission>WRITE</permission>
        <permission>DELETE</permission>
        <permission>PURGE</permission>
        <permission>SEARCH</permission>
    </permissions>
  • In JSON, the name in the name/value pair that lists the permissions is permission. For example:
    "permissions" : {
        "permission" : [ "READ", "WRITE", "DELETE", "PURGE", "SEARCH" ]
    }

availableServicePlan

The availableServicePlan data type describes the availableServicePlans resource for tenants.

Properties

The table below describes the properties included in the availableServicePlan data type.

Property nameData typeDescription
descriptionStringSpecifies the description of the service plan.
nameStringSpecifies the name of the service plan.
Example

Here’s an XML example of the availableServicePlan data type:

<availableServicePlan>
    <name>Platinum</name>
    <description>Most highly available, best performance -- suitable
        for data that will be frequently accessed or modified throughout its life</description>
</availableServicePlan>

chargebackData

The chargebackData data type describes the chargebackData property of the chargebackReport data type. The chargebackReport data type is used to generate chargeback reports.

Most of the properties in the chargebackData data type represent statistics that describe the usage of a given namespace or of all the namespaces owned by a given tenant. In a chargeback report, each set of these statistics applies to one namespace or tenant during a given reporting interval (for example, one hour or one day).

Chargeback statistics either reflect a point in time or are dynamic. Point-in-time statistics are measurements taken at the end of a reporting interval, such as the used storage capacity for a namespace at the end of an hour. Dynamic statistics are measurements, such as the number of reads or writes to a namespace, that are accumulated over time.

HCP accumulates dynamic statistics on an hourly basis, starting at the beginning of each hour. So, for example, if the reporting interval is an hour, one statistic might represent the number of successful writes to a namespace that occurred between 11:00:00 and 11:59:59. If the reporting interval is a day, each reported dynamic statistic is the sum of the hourly values for the day, where the day starts at 00:00:00 and ends at 23:59:59.

Properties

The table below describes the properties included in the chargebackData data type. When the output format for a chargebackReport resource is CSV, the properties included in the chargebackData data type are ordered. This table lists the properties in the order in which they appear in a CSV response body.

Property nameData typeDescriptionNotes
systemNameString

One of:

  • The name of the domain associated with the [hcp_system] network for the HCP system to which the set of aggregated statistics in the line applies
  • The name of the domain associated with the data access network for the tenant to which the set of aggregated statistics in the line applies
  • The name of the domain associated with the data access network for the tenant that owns the namespace to which the set of statistics in the line applies
tenantNameString

Either:

  • The name of the tenant to which the set of statistics applies
  • The name of the tenant that owns the namespace to which the set of statistics applies
namespaceNameStringThe name of the namespace to which the set of statistics applies.For aggregated namespace statistics, this property has no value.
startTimeString

The start time of the reporting interval to which the set of statistics applies, in this ISO 8601 format:

yyyy-MM-ddThh:mm:ssZ

Z represents the offset from UTC, in this format:

(+|-)hhmm

For example:

2017-02-18T14:00:00-0500

endTimeStringThe end time of the reporting interval to which the set of statistics applies, in the same ISO 8601 format as is used for the startTime property.
objectCountLong

The total number of objects currently stored in the given namespace or in all the namespaces owned by the given tenant.

Each version of an object counts as a separate object. The object count does not include object versions that are delete markers.

Each multipart object counts as a single object. Objects that are in the process of being created by multipart uploads are not included in the object count.

This is a point-in-time statistic.
ingestedVolumeLongThe total size of the currently stored data and custom metadata, in bytes, before it was added to the given namespace or to all the namespaces owned by the given tenant.This is a point-in-time statistic.

storageCapacity

Used

Long

The total number of bytes currently occupied by stored data in the given namespace or in all the namespaces owned by the given tenant. This includes object data, metadata, and any redundant data required to satisfy the applicable service plan.

Used storage capacity also includes storage occupied by the parts of in-progress multipart uploads that have already been written to HCP. Used storage capacity does not include replaced parts of multipart uploads, parts uploaded for aborted multipart uploads, or unused parts of completed multipart uploads.

This is a point-in-time statistic.
bytesInLong

The total number of bytes successfully written to the given namespace or to all the namespaces owned by the given tenant during the reporting interval.

The total number of bytes written includes all parts uploaded for multipart uploads regardless of whether the upload of the part has finished, the part was subsequently replaced, the multipart upload was aborted, or the part was not used in the completed multipart upload.

If data was compressed before being transmitted, this is the number of bytes before compression.

This is a dynamic statistic.
bytesOutLong

The total number of bytes read from the given namespace or from all the namespaces owned by the given tenant during the reporting interval.

If data (including XML for directory listings) was compressed before being transmitted, this is the number of bytes before compression.

This is a dynamic statistic.
readsLong

The total number of read operations performed in the given namespace or in all the namespaces owned by the given tenant during the reporting interval.

A read of a multipart object counts as a single read operation.

This is a dynamic statistic.
writesLong

The total number of write operations successfully performed in the given namespace or in all the namespaces owned by the given tenant during the reporting interval.

Each upload of a part for a multipart upload counts as a separate write operation. This applies even if the part was subsequently replaced, the multipart upload was aborted, or the part was not used in the completed multipart upload.

This is a dynamic statistic.
deletesLong

The total number of delete and purge operations performed in the given namespace or in all the namespaces owned by the given tenant during the reporting interval.

A delete of a multipart object counts as a single delete operation. The count of delete and purge operations does note include automatic deletions of replaced parts, parts of aborted multipart uploads, or unused parts of completed multipart uploads.

This is a dynamic statistic.
multipartObjectsLongThe total number of multipart objects currently stored in the given namespace or in all the namespaces owned by the given tenant.This is a point-in-time statistic.
mulltipartObject PartsLongThe total number of parts of multipart objects currently stored in the given namespace or in all the namespaces owned by the given tenant.This is a point-in-time statistic.
mulltipartObject BytesLongThe total number of bytes of object data in all the parts of multipart objects currently stored in the given namespace or in all the namespaces owned by the given tenant.This is a point-in-time statistic.
multipartUploadsLongThe total number of multipart uploads that are currently in progress in the given namespace or in all the namespaces owned by the given tenant.This is a point-in-time statistic.
multipartUpload PartsLong

The total number of successfully uploaded parts of multipart uploads that are currently in progress in the given namespace or in all the namespaces owned by the given tenant.

This number does not include replaced parts of multipart uploads, parts uploaded for aborted multipart uploads, or unused parts of completed multipart uploads.

This is a point-in-time statistic.
multipartUpload BytesLong

The total number of bytes of object data in all the successfully uploaded parts of multipart uploads that are currently in progress in the given namespace or in all the namespaces owned by the given tenant.

This number does not include bytes of data in replaced parts of multipart uploads, parts uploaded for aborted multipart uploads, or unused parts of completed multipart uploads.

This is a point-in-time statistic.
deletedString

One of:

  • false

    The namespace or tenant currently exists.

  • included

    For a tenant only, the statistics in the set include values for one or more namespaces that were subsequently deleted.

validBoolean

The status of the set of statistics in the line. Possible values are:

  • true

    HCP successfully collected all statistics in the set.

  • false

    The statistics in the set do not reflect all the activity that occurred during the reporting interval. This may be due, for example, to one or more nodes being unavailable during that time, to a network failure, or to other hardware issues.

Example

Here’s an XML example of the chargebackData data type that shows the properties for a namespace:

<chargebackData>
    <bytesIn>134243721</bytesIn>
    <bytesOut>87561</bytesOut>
    <deleted>false</deleted>
    <deletes>0</deletes>
    <endTime>2017-02-18T13:59:59-0500</endTime>
    <ingestedVolume>134243721</ingestedVolume>
    <multipartObjectBytes>93213889</multipartObjectBytes>
    <multipartObjectParts>7</multipartObjectParts>
    <multipartObjects>2</multipartObjects>
    <multipartUploadBytes>0</multipartUploadBytes>
    <multipartUploadParts>0</multipartUploadParts>
    <multipartUploads>0</multipartUploads>
    <namespaceName>finance</namespaceName>
    <objectCount>6</objectCount>
    <reads>1</reads>
    <startTime>2017-02-18T13:00:00-0500</startTime>
    <storageCapacityUsed>134270976</storageCapacityUsed>
    <systemName>hcp.example.com</systemName>
    <tenantName>europe</tenantName>
    <valid>true</valid>
    <writes>11</writes>
</chargebackData>

chargebackReport

The chargebackReport data type describes the chargebackReport resource for tenants and namespaces. You use this resource to generate chargeback reports for tenants and namespaces.

A chargeback report contains historical statistics about a tenant or namespace, broken out either by hour or by day. You can also generate chargeback reports that contain a single set of statistics for a given time period, such as a specific month.

Chargeback reports can serve as input to billing systems that need to determine charges for capacity and bandwidth usage at the tenant or namespace level. Because a chargeback report can cover a specified time period, you can create applications that generate these reports at regular intervals and feed those reports to your billing system.

TipAfter a tenant or namespace is deleted, you can no longer generate chargeback reports for it. Therefore, to ensure that you don’t lose usage statistics, you should take this fact into consideration when setting the regular interval at which to generate these reports.

Chargeback reports are also a good source of information for system analysis, enabling you to adjust storage and bandwidth allocations based on usage patterns.

Chargeback reports are available only for HCP tenants and namespaces. You cannot generate a chargeback report for the default tenant or namespace.

A chargeback report for a namespace contains statistics only for that namespace. A chargeback report for a tenant contains aggregated namespace statistics. For example, the number of read operations for a tenant during a given reporting interval is the total of the numbers of read operations that occurred in all the namespaces owned by that tenant during that reporting interval.

You can use a system-level user account to request a tenant chargeback report regardless of whether the tenant has granted system-level users administrative access to itself. To generate a namespace chargeback report using a system-level user account, system-level users must have administrative access to the owning tenant.

When generating a chargeback report, you use query parameters on the resource URL in the GET request to specify the reporting interval and the time period you want the report to cover. HCP keeps chargeback statistics for 180 days. As a result, chargeback reports cannot report statistics from more that 180 days in the past.

NoteIf you upgraded HCP less than 180 days ago from a release that does not support chargeback reports, the earliest available statistics are from the time the upgrade was completed.

The response to a chargebackReport GET request can be formatted as XML, JSON, or CSV.

Query parameters

You use query parameters appended to the request URL to specify the time period and reporting interval for a chargeback report. These parameters are all optional. Default values are used for any you omit.

Parameter typeParamter nameAccepted valuesNotes
Time periodstart=start-time

Use the ISO 8601 format

If you specify both a start time and an end time, the start time must be earlier than the end time.

  • With a reporting interval of hour or total, if you specify a start time that is not on an hour break, the first reporting interval in the report is the hour that includes the specified start time. For example, if you specify a start time of 9:45:00, the first reporting interval in the report starts at 9:00:00.
  • With a reporting interval of day, if you specify a start time that is not on a day break, the first reporting interval in the report is the day that includes the specified start time. For example, if you specify a start time of 9:45:00 on October 6th, the first reporting interval in the report starts at 00:00:00 on October 6th.
  • If you specify a start time that is earlier than the time of the earliest available chargeback statistics or if you omit the start parameter, the first reporting interval in the report is the interval that includes the earliest available statistics.
end=end-time

Use the ISO 8601 format

If you specify both a start time and an end time, the start time must be earlier than the end time.

  • With a reporting interval of hour or total, the last reporting interval in the report is the hour that includes the specified end time. For example, if you specify an end time of 9:00:00, the last reporting interval in the report ends at 9:59:59.
  • With a reporting interval of day, the last reporting interval in the report is the day that includes the specified end time. For example, if you specify an end time of 00:00:00 on October 6th, the last reporting interval in the report ends at 23:59:59 on October 6th.
  • If you specify an end time that is later than the current time or if you omit the end parameter, the last reporting interval in the report is the interval that includes the current time. The point-in-time statistics reported for this interval are the statistics at the current time. The dynamic statistics are the statistics accumulated so far for the interval.
Reporting intervalgranularity
  • hour

    The reporting interval is one hour.

  • day

    The reporting interval is one day.

  • total

    The reporting interval is the time period defined by the start and end times for the report. In this case, the report contains a single set of chargeback statistics.

The default is total.

These values are not case sensitive.

The statistics reported for the current reporting interval, if included in the chargeback report, may not reflect some reads and writes that have already occurred during the current hour. After the hour is past, however, the statistics for that hour are complete.
Query parameter examples

To get hourly statistics for the entire day of February 18, 2017:

start=2017-02-18T00:00:00-0500&end=2017-02-18T23:59:59-0500
    &granularity=hour

To get daily statistics for the week starting February 19, 2017:

start=2017-02-19T00:00:00-0500&end=2017-02-25T23:59:59-0500
    &granularity=day

To get a single set of statistics for the entire month of February 2017:

start=2017-02-01T00:00:00-0500&end=2017-02-29T23:59:59-0500
    &granularity=total

To get hourly statistics for the current day from 8:00 a.m. up to the current time, where the current day is February 22, 2017:

start=2017-02-22T08:00:00-0500&granularity=hour
Properties

The table below describes the property included in the chargebackReport data type.

Property nameData typeDescriptionNotes
chargebackData

chargeback

Data

Specifies statistics that describe the usage of a given namespace or of all the namespaces owned by a given tenant.The response body includes one instance of this property for each reporting interval in the time period specified by the query parameters in the GET request for the chargebackReport resource.

cifsProtocol

The cifsProtocol data type describes the cifs resource for HCPnamespaces.

Properties

The table below describes the properties included in the cifsProtocol data type.

Property nameData typeDescription
caseForcingBoolean

Specifies whether the CIFS protocol is case forcing for the namespace. Valid values are:

  • UPPER

    The protocol changes object names to all uppercase in requests it passes to HCP.

  • LOWER

    The protocol changes object names to all lowercase in requests it passes to HCP.

  • DISABLED

    The protocol is not case forcing.

The default is DISABLED.

These values are not case sensitive.

caseSensitiveBoolean

Specifies whether the CIFS protocol is case sensitive for the namespace. Valid values are:

  • true

    The protocol is case sensitive.

  • false

    The protocol is not case sensitive.

The default is true.

enabledBoolean

Specifies whether the CIFS protocol is enabled for the namespace. Valid values are:

  • true

    CIFS is enabled.

  • false

    CIFS is disabled.

The default is false.

ipSettingsipSettingsSpecifies which IP addresses can and cannot access the namespace through the CIFS protocol.
requiresAuthenticationBoolean

Specifies whether user authentication is required or allowed for access to the namespace through the CIFS protocol. Valid values are:

  • true

    User authentication is required.

  • false

    User authentication is allowed.

The default is true.

This property can be set to true only if the owning tenant supports AD authentication.

Example

Here’s an XML example of the cifsProtocol data type:

<cifsProtocol>
    <caseForcing>DISABLED</caseForcing/>
    <caseSensitive>true</caseSensitive>
    <enabled>true</enabled>
    <ipSettings>
         <allowAddresses>
             <ipAddress>192.168.140.10</ipAddress>
             <ipAddress>192.168.140.14</ipAddress>
             <ipAddress>192.168.140.15</ipAddress>
             <ipAddress>192.168.149.0/24</ipAddress>
         </allowAddresses>
         <denyAddresses>
             <ipAddress>192.168.149.5</ipAddress>
         </denyAddresses>
    </ipSettings>
    <requiresAuthentication>true</requiresAuthentication>
</cifsProtocol>

complianceSettings

The complianceSettings data type describes the complianceSettings resource for namespaces.

Properties

The table below describes the properties included in the complianceSettings data type.

Property nameData typeDescriptionNotes
customMetadataChangesString

Specifies which operations are allowed with custom metadata for objects under retention. Valid values are:

  • ADD

    Allows custom metadata to be added for objects under retention but not replaced or deleted

  • ALL

    Allows custom metadata to be added, replaced, and deleted for objects under retention

  • NONE

    Disallows all custom metadata operations for objects under retention

The default is ADD.

These values are not case sensitive.

dispositionEnabledBoolean

Specifies whether objects with expired retention periods should automatically be deleted from the namespace. Valid values are:

  • true

    Disposition is enabled.

  • false

    Disposition is not enabled.

The default is false.

For disposition to take effect at the namespace level, it must also be enabled in the HCPsystem configuration.
minimumRetentionAfterInitialUnspecifiedString

For an HCP namespace, specifies that the retention set on Initial Unspecified objects must be greater than the Minimum Retention after Initial Unspecified value.

The default is 0 (zero) years, 0 months, and 0 days.

This property is not valid for the default namespace.
retentionDefaultString

For an HCP namespace, specifies the default retention setting for objects added to the namespace. Valid values are special values, offsets, retention classes, and fixed dates.

The default is 0 (zero), which is equivalent to Deletion Allowed.

This property is not valid for the default namespace.
shreddingDefaultBoolean

For an HCP namespace, specifies the default shred setting for objects added to the namespaces. Valid values are:

  • true

    New objects are marked for shredding.

  • false

    New objects are not marked for shredding.

The default is false.

This property is not valid for the default namespace.

Once an object is marked for shredding, its shred setting cannot be changed.

Example

Here’s an XML example of the complianceSettings data type:

<complianceSettings>
    <customMetadataChanges>ALL</customMetadataChanges>
    <retentionDefault>A+7Y</retentionDefault>
    <minimumRetentionAfterInitialUnspecified>19y+0M+7d</minimumRetentionAfterInitialUnspecified>
    <dispositionEnabled>true</dispositionEnabled>
    <shreddingDefault>false</shreddingDefault>
</complianceSettings>

consoleSecurity

The consoleSecurity data type describes the consoleSecurity resource for tenants.

Properties

The table below describes the properties included in the consoleSecurity data type.

Property nameData typeDescriptionNotes
disableAfterAttemptsInteger

Specifies the number of times a locally authenticated or RADIUS-authenticated user can enter an incorrect password before the user account is automatically disabled. Valid values are integers in the range zero through 999. The default is five.

A value of zero means accounts are never disabled due to failed login attempts.

If the last locally authenticated user account with the security role is disabled due to failed login attempts and no group accounts have the security role, the user account is reenabled automatically after one hour.
disableAfterInactiveDaysInteger

Specifies the number of days an HCP user account can remain inactive before it’s automatically disabled. Valid values are integers in the range zero through 999. The default is 180 days.

A value of zero means accounts are never automatically disabled due to inactivity.

If no group accounts have the security role, the last locally authenticated user account with the security role is not automatically disabled due to inactivity.

forcePasswordChange

Days

Integer

Specifies the number of days after which locally authenticated users are automatically forced to change their passwords. Valid values are integers in the range zero through 999,999. The default is 180 days.

A value of zero means users are never automatically forced to change their passwords.

ipSettingsipSettingsSpecifies which IP addresses can and cannot access the Tenant Management Console.
loginMessageStringSpecifies message text to appear on the login page of the Tenant Management Console and Search Console. This text is optional. If specified, it can be up to 1,024 characters long and can contain any valid UTF-8 characters, including white space.
logoutOnInactiveIntegerSpecifies the number of minutes a Tenant Management Console or Search Console session started with an explicit login can be inactive before it times out. Valid values are integers in the range zero through 999. The default is ten.
minimumPasswordLengthIntegerSpecifies the minimum number of characters for user account passwords. Valid values are integers in the range two through 64. The default is six.
Example

Here’s an XML example of the consoleSecurity data type:

<consoleSecurity>
    <disableAfterAttempts>3</disableAfterAttempts>
    <disableAfterInactiveDays>30</disableAfterInactiveDays>
    <forcePasswordChangeDays>45</forcePasswordChangeDays>
    <ipSettings>
         <allowAddresses>
             <ipAddress>192.168.103.18</ipAddress>
             <ipAddress>192.168.103.24</ipAddress>
             <ipAddress>192.168.103.25</ipAddress>
         </allowAddresses>
         <allowIfInBothLists>false</allowIfInBothLists>
         <denyAddresses/>
     </ipSettings>
    <loginMessage></loginMessage>
    <logoutOnInactive>20</logoutOnInactive>
    <minimumPasswordLength>6</minimumPasswordLength>
</consoleSecurity>

contactInfo

The contactInfo data type describes the contactInfo resource for tenants.

Properties

The table below describes the properties included in the contactInfo data type. All of these properties are optional. The property values can contain any valid UTF-8 characters, including white space.

Property nameData typeDescriptionNotes
address1StringSpecifies the first line of an address for the tenant contact
address2StringSpecifies the second line of an address for the tenant contact
cityStringSpecifies the city for the tenant contact
countryOrRegionStringSpecifies the country for the tenant contact
emailAddressStringSpecifies a valid email address for the tenant contact
extensionStringSpecifies a telephone number extension for the tenant contact
firstNameStringSpecifies the first name of the tenant contact
lastNameStringSpecifies the last name of the tenant contact
primaryPhoneStringSpecifies a telephone number for the tenant contactDo not include a telephone number extension. Use the extension property for that.
stateStringSpecifies the state or province for the tenant contact
zipOrPostalCodeStringSpecifies the postal code for the tenant contact
Example

Here’s an XML example of the contactInfo data type:

<contactinfo>
    <address1>Exmple Co., Finance Dept.</address1>
    <address2>10 Main St.</address2>
    <city>Anytown</city>
    <countryOrRegion>USA</countryOrRegion>
    <emailAddress>lgreen@example.com</emailAddress>
    <extension>123</extension>
    <firstName>Lee</firstName>
    <lastName>Green</lastName>
    <zipOrPostalCode>12345</zipOrPostalCode>
    <primaryPhone>555-555-5555</primaryPhone>
    <state>MA</state>
</contactinfo>

contentClass

The contentClass data type describes the contentClasses resource for tenants.

Properties

The table below describes the properties included in the contentClass data type.

Property nameData typeDescriptionNotes
contentProperties

content

Properties

Specifies the set of content properties in the content class.

This property is optional on a PUT request.

The set of content properties specified in the request body replaces the set of content properties currently in the content class. To remove all content properties, specify an empty set.

nameStringSpecifies the name of the content class. Content class names must be from one through 64 characters long, can contain any valid UTF-8 characters, including white space, and are not case sensitive.This property is required on a PUT request.
namespacesListAssociates zero, one, or more namespaces with the content class. Valid values are the names of existing search-enabled namespaces.

This property is optional on a PUT request.

The set of namespaces specified in the request body replaces the set of namespaces currently associated with the content class. To dissociate all namespaces from the content class, specify an empty set.

In XML, element that identifies each namespace is name. In JSON, the name in the name/value pair that lists the namespaces is name.

Example

Here’s an XML example of the contentClass data type:

<contentClass>
    <name>DICOM</name>
    <contentProperties>
        <contentProperty>
            <name>Doctor_Name</name>
            <expression>/dicom_image/doctor/name</expression>
            <type>STRING</type>
            <multivalued>false</multivalued>
            <format></format>
        </contentProperty>
        <contentProperty>
            <name>Doctor_Specialty</name>
            <expression>/dicom_image/doctor/specialties/specialty</expression>
            <type>STRING</type>
            <multivalued>true</multivalued>
            <format></format>
        </contentProperty>
        <contentProperty>
            <name>Followup_Needed</name>
            <expression>/dicom_image/followup_needed</expression>
            <type>BOOLEAN</type>
            <multivalued>false</multivalued>
            <format></format>
        </contentProperty>
        <contentProperty>
            <name>Image_Date</name>
            <expression>/dicom_image/image/date</expression>
            <type>DATE</type>
            <multivalued>false</multivalued>
            <format>MM/dd/yyyy</format>
        </contentProperty>
        <contentProperty>
            <name>Image_Type</name>
            <expression>/dicom_image/image/@type</expression>
            <type>STRING</type>
            <multivalued>false</multivalued>
            <format></format>
        </contentProperty>
        <contentProperty>
            <name>Patient_ID</name>
            <expression>/dicom_image/patient/id</expression>
            <type>INTEGER</type>
            <multivalued>false</multivalued>
            <format></format>
        </contentProperty>
        <contentProperty>
            <name>Patient_Name</name>
            <expression>/dicom_image/patient/name</expression>
            <type>STRING</type>
            <multivalued>false</multivalued>
            <format></format>
        </contentProperty>
    </contentProperties>
    <namespaces>
        <name>Medical-Records</name>
    </namespaces>
</contentClass>

contentProperty

The contentProperties data type describes the contentProperties property of the contentClass data type.

Properties

The table below describes the properties included in the contentProperty data type.

Property nameData typeDescriptionNotes
expressionString

Specifies the expression for the content property. Valid values are valid XPath expressions, optionally prefixed with an annotation name, in this format:

@annot-name:xpath-expression

This property is required.
formatString

Specifies the format for the content property. Valid values are specific to each data type for which the format property is valid:

  • For DATE, the value must be a valid datetime format. If you don't specify a format, the metadata query engine indexes only values that match patterns such as MM/DD/yyy, MM-dd-yyy, yyy-MM-dd, or yyy-MM-dd'T'HH:mm:ssZ.
  • For FLOAT, the value must be a valid number format that can map content property vales to decimal numbers. If you don't specify a format, the metadata query engine indexes only sequences of digits that optionally include one decimal point.
  • For INTEGER, the value must be a valid number format that can map content property values to integers. If you don't specify a format, the metadata query engine indexes only sequences of digits with no special characters.
This property is optional and can have a value only when the value of the types property is DATE, FLOAT, or INTEGER.
multivaluedBoolean

Specifies whether the content property is single-valued or multivalued. Valid values are:

  • true

    The content property can have multiple values for any given object.

  • false

    The content property can have only one value for any given object.

The default is false.

nameStringSpecifies the name of the content property. Content property names must be from one through 25 characters long, can contain only alphanumeric characters and underscores (_), and are case sensitive. White space is not allowed.This property is required.
typeString

Specifies the data type of the content property. Valid values are:

  • BOOLEAN

    The metadata query engine indexes the value as true or false.

  • DATE

    The metadata query engine indexes the value as a date and time.

  • FLOAT

    The metadata query engine indexes the value as a decimal number with or without an exponent, depending on the value.

  • FULLTEXT

    The metadata query engine indexes the value as a text string after breaking it into tokens.

  • INTEGER

    The metadata query engine indexes the value as an integer.

  • STRING

    The metadata query engine indexes the content property values as text strings.

These values are not case sensitive.

This property is required.
Example

Here’s an XML example of the contentProperty data type:

<contentProperty>
    <name>Image_Date</name>
    <expression>/dicom_image/image/date</expression>
    <type>DATE</type>
    <multivalued>false</multivalued>
    <format>MM/dd/yyyy</format>
</contentProperty>

contentProperties

The contentProperties data type describes the contentProperties property of the contentClass data type.

Properties

The table below describes the property included in the contentProperties data type.

Property nameData typeDescription
contentProperty

content

Property

Specifies a content property.
Example

Here’s an XML example of the contentProperty data type:

<contentProperty>
    <name>Image_Date</name>
    <expression>/dicom_image/image/date</expression>
    <type>DATE</type>
    <multivalued>false</multivalued>
    <format>MM/dd/yyyy</format>
</contentProperty>

cors data type

The cors data type describes the cors resource for tenants and namespaces.

The cors data type is a string in a CDATA section that specifies a CORS rules configuration.

Example

Here is an example of the cors data type.

<cors><![CDATA[<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <CORSConfiguration>
          <CORSRule>
               <AllowedOrigin>;:~`!@#$%^()-_+={}[]|\",.?/*</AllowedOrigin>
               <AllowedMethod>PUT</AllowedMethod>
               <AllowedHeader>&gt;someHeader</AllowedHeader>
               <AllowedHeader>;~`!@#$%^()-_+={}[]|\".?/*</AllowedHeader>
          </CORSRule>
     </CORSConfiguration>
]]></cors>

customMetadataIndexingSettings

The customMetadataIndexingSettings data type describes the customMetadataIndexingSettings resource for namespaces.

Properties

The table below describes the properties included in the customMetadataIndexingSettings data type.

Property nameData typeDescriptionNotes
contentClassesList

Associates zero, one, or more content classes with the namespace. Valid values are the names of existing content classes.

Content class names are case sensitive.

The set of content classes specified in the request body replaces the set of content classes currently associated with the namespace. To dissociate all content classes from the namespace, specify an empty set.

In XML, element that identifies each content class is name.In JSON, the name in the name/value pair that lists the content classes is name.

fullIndexingEnabledBoolean

Specifies whether the metadata query engine indexes the full text of custom metadata. Valid values are:

  • true

    The metadata query engine indexes the full text of custom metadata.

  • false

    The metadata query engine does not index the full text of custom metadata.

The default is false.

You can set this property to true only while custom metadata indexing is enabled for the namespace.
excludedAnnotationsString

Specifies a comma-separated list of the names of annotations to be excluded from indexing by the metadata query engine.

Instead of explicit names, you can use patterns. The wildcard character for pattern matching is the asterisk (*), which matches any number of characters of any type, including none. The asterisk can occur anywhere in the pattern.

Annotation names are case sensitive.

The list of annotation names you specify for this property replaces the current list of annotation names. To remove all annotation names from the list, specify this property with no value.

You can set a value for this property only while custom metadata indexing is enabled for the namespace.

Disabling custom metadata indexing for the namespace automatically deletes the list of excluded annotation for the namespace.

Example

Here’s an XML example of the customMetadataIndexingSettings data type:

<customMetadataIndexingSettings>
    <contentClasses>
         <name>DICOM</name>
         <name>Appointment</name>
    </contentClasses>
    <excludedAnnotations>misc*, email</excludedAnnotations>
    <fullIndexingEnabled>false</fullIndexingEnabled>
</customMetadataIndexingSettings>

dataAccessPermissions

The dataAccessPermissions data type describes the dataAccessPermissions resource for group accounts and user accounts.

Properties

The table below describes the property included in the dataAccessPermissions data type.

PropertyData typeDescriptionNotes
namespacePermission

namespace

Permission

Specifies the permissions the user or group account has for a namespace.Include one instance of this property for each namespace for which you want to change the permissions. If you omit a namespace, its permissions are not changed.
Example

Here’s an XML example of the dataAccessPermissions data type:

<dataAccessPermissions>
    <namespacePermission>
         <namespaceName>Accounts-Payable</namespaceName>
         <permissions>
             <permission>BROWSE</permission>
             <permission>READ</permission>
         </permissions>
    </namespacePermission>
    <namespacePermission>
         <namespaceName>Accounts-Receivable</namespaceName>
         <permissions>
             <permission>BROWSE</permission>
             <permission>SEARCH</permission>
             <permission>PURGE</permission>
             <permission>DELETE</permission>
             <permission>READ</permission>
             <permission>WRITE</permission>
         </permissions>
    </namespacePermission>
</dataAccessPermissions>

emailNotification

The emailNotification data type describes the emailNotification resource for tenants.

Properties

The table below describes the properties included in the emailNotification data type.

PropertyData typeDescriptionNotes
emailTemplate

email

Template

Specifies the template for email messages HCP sends to the specified recipients.

The email template specified in the request body replaces the current email template. To restore the default email template, specify the emailTemplate property with no value.

For information about the default email template, see Email template defaults.

enabledBoolean

Specifies whether email notification is enabled for the tenant. Valid values are:

  • true

    Email notification is enabled.

  • false

    Email notification is disabled.

The default is false.

Email notification at the tenant level is supported only if HCP is configured to support it at the system level.
recipientsrecipientsSpecifies the set of recipients for email notification.

The set of recipients specified in the request body replaces the set of recipients currently configured for email notification. To remove all email recipients, specify an empty set.

Recipients are added to the Bcc list for each email.

Example

Here’s an XML example of the emailNotification data type:

<emailNotification>
    <enabled>true</enabled>
    <emailTemplate>
         <from>log@$location</from>
         <subject>$severity - $shortText</subject>
         <body>A message was written to the tenant log on $date.\n\n$reason\n\n
             $action</body>
    </emailTemplate>
    <recipients>
         <recipient>
              <address>lgreen@example.com, sgold@example.com</address>
              <importance>MAJOR</importance>
              <severity>ERROR</severity>
              <type>GENERAL,SECURITY</type>
          </recipient>
          <recipient>
              <address>mwhite@example.com</address>
              <importance>ALL</importance>
              <severity>WARNING</severity>
              <type>COMPLIANCE</type>
          </recipient>
    </recipients>
</emailNotification>

emailTemplate

The emailTemplate data type describes the emailTemplate property of the emailNotification data type.

Properties

The table below describes the properties included in the emailTemplate data type.

PropertyData typeDescriptionNotes
bodyString

Specifies the format of the body of the email messages HCPsends when email notification is enabled. Valid values include any combination of plain text and email template variables.

Plain text can include spaces and line breaks but not tabs. The character sequence consisting of a backslash (\) followed by a lowercase n creates a line break.

To change the body in the email template to blank, include the from and subject properties in the request body and omit the body property.
fromString

Specifies the content of the email From line. Valid values include any combination of plain text and email template variables and must have the form of a valid email address.

Some email servers require that the value in the From line be an email address that is already known to the server.

If this property is included in the request body, the subject property must also be included.
subjectString

Specifies the content of the email Subject line. Valid values include any combination of plain text and email template variables.

Plain text can include spaces but not line breaks or tabs.

If this property is included in the request body, the from property must also be included.
Variables

The values you specify for the body, from, and subject properties of the emailTemplate data type can include variables that correspond to the information available for each log message (for example, the severity of the event that triggered the message or the short description of the event). When sending email, HCP replaces the variables in the email message with the applicable information.

To include a variable in the email template, you specify the variable name preceded by the dollar sign ($). A dollar sign followed by anything other than a variable name is displayed as a dollar sign in the email HCP sends.

The list below lists the variables you can use in the email template.

  • $action

    The action to take in response to the message

  • $date

    The date and time at which the event occurred (for example, Wed Feb 8 2017 3:15:57 PM EST)

  • $fullText

    The full text of the message

  • $id

    The message ID

  • $location

    The fully qualified name of the HCP system on which the event occurred (for example, hcp-ma.example.com)

  • $origin

    For user-initiated events, the IP address from which the event request was sent and the port through which HCP received the event request, separated by a colon (for example, 192.168.152.181:8000)

  • $reason

    The reason why HCP issued the message

  • $severity

    The severity of the event that triggered the message

  • $shortText

    A brief description of the event that triggered the message

  • $type

    The type of message (General, Security, or Compliance), preceded by Important and a comma if the message is important (for example, Important, Security)

  • $user

    The user ID and username of the event initiator (for example, 105ff38f-4770-4f98-b5b3-8371ab0af359 lgreen)

Defaults

The list below shows the format of the default email template.

  • From

    log@$location

  • Subject

    [$severity] $shortText

  • Body

    The following event occurred on $date:
    $fullText
    
    Reason:
    $reason
    
    Action:
    $action
    
    Details:
    User: $user
    Origin: $origin
Example

Here’s an XML example of the emailTemplate data type:

<emailTemplate>
    <from>log@$location</from>
    <body>A message was written to the tenant log on $date.\n\n$reason\n\n
         $action</body>
    <subject>$severity - $shortText</subject>
</emailTemplate>

groupAccount

The groupAccount data type describes the groupAccounts resource.

Properties

The table below describes the properties included in the groupAccount data type.

PropertyData TypeDescriptionNotes

allowNamespace

Management

Boolean

Specifies whether the group account has the allow namespace management property. Valid values are:

  • true

    The group account has the allow namespace property.

  • false

    The group account does not have the allow namespace management property.

On a PUT request, the default is true if the roles property includes ADMINISTRATOR in the same request; otherwise, the default is false.

On a POST request, adding ADMINISTRATOR to the roles for the group account automatically enables the allow namespace management property for the account.

Users in groups with the allow namespace management property can use the HCP management and S3 compatible APIs to:

  • Create namespaces
  • List, view and change the versioning status of, and delete namespaces they own
This property is not valid on a PUT request. It is valid on a POST request only if the user making the request has the administrator role.
externalGroupIDStringSpecifies the security identifier (SID) of the AD group that corresponds to the HCP group account. For a PUT request, valid values are the SIDs of AD groups defined in the AD forest supported by HCP.

Either this property or the groupname property is required on a PUT request. If you include both properties in the request body, they must identify the same AD group.

This property is not valid on a POST request. It is returned only by a verbose GET request and only when the user making the request has the security role.

groupnameString

Specifies the name of the HCP group account. For a PUT request, valid values are the names of AD groups defined in the AD forest supported by HCP, in either of these formats:

group-name

group-name@ad-domain- name

If you omit the domain name, HCP uses the AD domain specified in the system configuration.

Be sure to use the second format if a group with the specified name exists in more than one domain in the AD forest or if the group name looks like a SID.

Either this property or the externalGroupID property is required on a PUT request. If you include both properties in the request body, they must identify the same AD group.

This property is not valid on a POST request.

rolesList

Associates zero, one, or more roles with the group account. Valid values for roles are:

  • ADMINISTRATOR
  • COMPLIANCE
  • MONITOR
  • SECURITY

These values are not case sensitive.

The default is no roles.

This property is valid on a POST request and returned by a GET request only when the user making the request has the security role.

A user with the ADMINISTRATOR role cannot POST this property.

For an existing group account, the set of roles specified in the request body replaces the set of roles currently associated with the group account. To remove all roles, specify an empty set.

In XML, the element that identifies each role is role. In JSON, the name in the name/value pair that lists the roles is role.

Example

Here’s an XML example of the groupAccount data type:

<groupAccount>
    <allowNamespaceManagement>false</allowNamespaceManagement>
    <externalGroupID>S-1-5-21-1522923621-2272695913-102089983-3621
    </externalGroupID>
    <groupname>hcp-admin@ad.example.com</groupname>
    <roles>
         <role>MONITOR</role>
         <role>ADMINISTRATOR</role>
    </roles>
</groupAccount>

httpProtocol

The httpProtocol data type describes the http resource for HCPnamespaces. This data type includes properties for the REST, S3 compatible, HSwift, and WebDAV namespace access protocols.

Properties

The table below describes the properties included in the httpProtocol data type.

PropertyData typeDescriptionNotes
hs3EnabledBooleanSpecifies whether the Hitachi API for Amazon S3 is enabled for the namespace. Valid values are:
  • true

    The Hitachi API for Amazon S3 is enabled.

  • false

    The Hitachi API for Amazon S3 is disabled.

The default is false.

This property can be set to true only if ACLs are enabled for the namespace.
hs3Requires AuthenticationBooleanSpecifies whether user authentication is required or optional for access to the namespace through the Hitachi API for Amazon S3. Valid values are:
  • true

    User authentication is required.

  • false

    User authentication is optional.

The default is true.

hswiftEnabledBooleanSpecifies whether the HSwift API is enabled for the namespace. Valid values are:
  • true

    The HSwift API is enabled.

  • false

    The HSwift API is disabled.

The default is false.

hswiftRequires AuthenticationBooleanSpecifies whether user authentication is required or optional for access to the namespace through the HSwift API. Valid values are:
  • true

    User authentication is required.

  • false

    User authentication is optional.

The default is true.

httpActiveDirectorySSO

Enabled

BooleanSpecifies whether HCP supports AD single sign-on for access to the namespace through the REST and S3 compatible APIs. Valid values are:
  • true

    HCP supports AD single sign-on for access to the namespace through the REST and S3 compatible APIs.

  • false

    HCP does not support AD single sign-on for access to the namespace through the REST and S3 compatible APIs.

The default is true.

This property is valid on a POST request only if owning the tenant supports AD authentication.

You can set the value of this property to true only while HTTP or HTTPS is enabled. Disabling both HTTP and HTTPS automatically disables this property.

httpEnabledBooleanSpecifies whether the HTTP port is open for HTTP and WebDAV access to the namespace without SSL security. Valid values are:
  • true

    The HTTP port is open.

  • false

    The HTTP port is closed.

The default is false.

httpsEnabledBooleanSpecifies whether the HTTPS port is open for HTTP and WebDAV access to the namespace with SSL security. Valid values are:
  • true

    The HTTPS port is open.

  • false

    The HTTPS port is closed.

The default is true.

Certain countries restrict the use of HTTPS. If the HCP system does not have HTTPS enabled, the httpsEnabled value cannot be set to true.
ipSettingsipSettingsSpecifies which IP addresses can and cannot access the namespace through the HTTP and WebDAV protocols.
restEnabledBooleanSpecifies whether the RESTful implementation of the HTTP protocol is enabled for the namespace. Valid values are:
  • true

    The RESTful implementation of the HTTP protocol is enabled.

  • false

    The RESTful implementation of the HTTP protocol is disabled.

The default is true.

restRequires AuthenticationBooleanSpecifies whether user authentication is required or optional for access to the namespace through the HTTP protocol. Valid values are:
  • true

    User authentication is required.

  • false

    User authentication is optional.

The default is true.

webdavBasicAuth EnabledBooleanSpecifies whether the WebDAV protocol requires basic authentication for access to the namespace. Valid values are:
  • true

    WebDAV requires basic authentication.

  • false

    WebDAV does not require basic authentication.

The default is false.

You can set the value of this property to true only if a WebDAV username and password already exist or are specified by the webdav-BasicAuthUsername and webdavBasicAuthPassword properties in the same request.
webdavBasicAuth PasswordStringSpecifies the password to use for basic authentication with the WebDAV protocol.

You can specify a value for this property only if a basic authentication username already exists or is specified by the webdavBasicAuth-Username property in the same request.

To remove the basic authentication password, specify the webdavBasic-AuthPassword property with no value. You can remove the password only if you remove the basic authentication username in the same request.

webdavBasicAuth UsernameString

Specifies the username to use for basic authentication with the WebDAV protocol.

Usernames must be from one through 64 characters long and can contain any valid UTF-8 characters but cannot start with an opening square bracket ([). White space is allowed.

Usernames are not case sensitive.

You can specify a value for this property only if a basic authentication password already exists or is specified by the webdavBasicAuth-Password property in the same request.

To remove the basic authentication username, specify the webdavBasic-AuthUsername property with no value. You can remove the username only if you remove the basic authentication password in the same request.

webdavCustom MetadataBooleanSpecifies whether WebDAV dead properties can be stored as custom metadata. Valid values are:
  • true

    Dead properties can be stored as custom metadata.

  • false

    Dead properties cannot be stored as custom metadata.

The default is false.

webdavEnabledBooleanSpecifies whether the WebDAV protocol is enabled for the namespace. Valid values are:
  • true

    The WebDAV protocol is enabled.

  • false

    The WebDAV protocol is disabled.

The default is false.

Example

Here’s an XML example of the httpProtocol data type:

<httpProtocol>
    <hswiftEnabled>false</hswiftEnabled>
    <hswiftRequiresAuthentication>false</hswiftRequiresAuthentication>
    <hs3Enabled>false</hs3Enabled>
    <hs3RequiresAuthentication>false</hs3RequiresAuthentication>
    <httpActiveDirectorySSOEnabled>true</httpActiveDirectorySSOEnabled>
    <httpEnabled>false</httpEnabled>
    <httpsEnabled>true</httpsEnabled>
    <ipSettings>
         <allowAddresses>
             <ipAddress>192.168.140.10</ipAddress>
             <ipAddress>192.168.140.14</ipAddress>
             <ipAddress>192.168.140.15</ipAddress>
             <ipAddress>192.168.149.0/24</ipAddress>
         </allowAddresses>
         <allowIfInBothLists>false</allowIfInBothLists>
         <denyAddresses>
             <ipAddress>192.168.149.5</ipAddress>
         </denyAddresses>
    </ipSettings>
    <restEnabled>true</restEnabled>
    <restRequiresAuthentication>true</restRequiresAuthentication>
    <webdavBasicAuthEnabled>false</webdavBasicAuthEnabled>
    <webdavBasicAuthPassword></webdavBasicAuthPassword>
    <webdavBasicAuthUsername></webdavBasicAuthUsername>
    <webdavCustomMetadata>false</webdavCustomMetadata>
    <webdavEnabled>false</webdavEnabled>
</httpProtocol>

ipSettings

The ipSettings data type describes the ipSettings property of these data types:

  • cifsProtocol
  • consoleSecurity
  • httpProtocol
  • nfsProtocol
  • protocols
  • searchSecurity
  • smtpProtocol
Properties

The table below describes the properties included in the ipSettings data type.

PropertyData typeDescriptionNotes
allowAddresses

allow

Addresses

Specifies the IP addresses to be allowed access to HCPthrough the given interface. By default, the set of IP addresses includes only 0.0.0.0/0.

The set of IP addresses specified in the request body replaces the set of IP addresses currently allowed access to HCP through the given interface. To remove all IP addresses, specify an empty set.

In XML, each IP address specification is the value of an element named ipAddress. In JSON, the name in the name/value pair that specifies the IP addresses is ipAddress.

allowIfInBothListsBoolean

Specifies how HCP should handle IP addresses that are either both allowed and denied or neither allowed nor denied access to HCP through the given interface. Valid values are true and false. The default is true.

For the effects of specifying true or false, see allowIfInBothLists property effects list below.

This property is not valid for the cifsProtocol, nfsProtocol, and smtpProtocol data types.

denyAddresses

deny

Addresses

Specifies the IP addresses to be denied access to HCP through the given interface. By default, the set of IP addresses is empty.

This property is not valid for the nfsProtocol data type.

The set of IP addresses specified in the request body replaces the set of IP addresses currently denied access to HCP through the given interface. To remove all IP addresses, specify an empty set.

In XML, each IP address specification is the value of an element named ipAddress. In JSON, the name in the name/value pair that specifies the IP addresses is ipAddress.

allowAddresses and denyAddresses list entries

Each ipAddress entry within an allowAddresses or denyAddresses property can have a value of:

  • An individual IP address.
  • A comma-separated list of IP addresses.
  • A range of IP addresses specified as ip-address/subnet-mask (for example, 192.168.100.197/255.255.255.0).
  • A range of IP addresses specified in CIDR format (for example, 192.168.100.0/24). The CIDR entry that matches all IP addresses is 0.0.0.0/0.
allowIfInBothLists property effects

The table below describes the effects of specifying true or false for the allowIfInBothLists property.

Listed IP addressestruefalse

allowAddresses: none

denyAddresses: none

All IP addresses can access HCP through the given interface.No IP addresses can access HCP through the given interface.

allowAddresses: at least one

denyAddresses: none

All IP addresses can access HCP through the given interface.Only IP addresses in the allowAddresses list can access HCP through the given interface.

allowAddresses: none

denyAddresses: at least one

All IP addresses not in the denyAddresses list can access HCP through the given interface. IP addresses in the denyAddresses list cannot.No IP addresses can access HCP through the given interface.

allowAddresses: at least one

denyAddresses: at least one

IP addresses appearing in both or neither of the lists can access HCP through the given interface.IP addresses appearing in both or neither of the lists cannot access HCP through the given interface.
Example

Here’s an XML example of the ipSettings data type:

<ipSettings>
    <allowAddresses>
         <ipAddress>192.168.140.10</ipAddress>
         <ipAddress>192.168.140.14</ipAddress>
         <ipAddress>192.168.140.15</ipAddress>
         <ipAddress>192.168.149.0/24</ipAddress>
    </allowAddresses>
    <allowIfInBothLists>false</allowIfInBothLists>
    <denyAddresses>
         <ipAddress>192.168.149.5</ipAddress>
    </denyAddresses>
</ipSettings>

namespace

The namespace data type describes the namespaces resource.

Properties

The table below describes the properties included in the namespace data type.

PropertyData typeDescriptionNotes
aclsUsageStringSpecifies whether the namespace supports access control lists (ACLs) and, if so, whether HCP honors ACLs in the namespace. Valid values are:
  • NOT_ENABLED

    The namespace does not support ACLs.

  • ENFORCED

    The namespace supports ACLs, and HCP honors ACLs in the namespace.

  • NOT_ENFORCED

    The namespace supports ACLs, but HCP does not honor ACLs in the namespace.

The default is NOT_ENABLED.

These values are not case sensitive.

This property is optional on a PUT request.

You can change the value of this property from NOT_ENABLED to ENFORCED or NOT_ENFORCED but not from ENFORCED or NOT_ENFORCED to NOT_ENABLED.

This property is not valid for the default namespace.

allowErasureCodingBoolean

For an HCP namespace, specifies whether HCP is allowed to use erasure coding to implement replication of the objects in the namespace. Valid values are:

  • true

    HCP is allowed to use erasure coding for replication of the namespace.

  • false

    HCP is not allowed to use erasure coding for replication of the namespace.

If the tenant is allowed to manage erasure coding for namespaces, the default is the setting specified by the namespace defaults for the tenant. If the tenant does not have this ability, the default is to allow erasure coding for namespaces that are cloud optimized.

This property is valid on a PUT or POST request only if the owning tenant is allowed to manage erasure coding for its namespaces.

This property is optional on a PUT request.

You can set the value of this property to true on a PUT request only if the value of the optimizedFor property is set to true in the same request or if new namespaces are cloud optimized by default.

You can set the value of this property to true on a POST request only if the namespace is already cloud optimized or the optimizedFor property is set to true in the same request.

This property is not returned by any GET request for a namespace that is not selected for replication or for which the owning tenant is not allowed to manage erasure coding for its namespaces.

This property is not valid for the default namespace.

allowPermissionAnd OwnershipChangesBoolean

Specifies whether changes to POSIX UIDs, GIDs, and permissions and to object ownership are allowed for objects under retention in the namespace. Valid value are:

  • true

    Changes to POSIX UIDs, GIDs, and permissions and to object ownership are allowed for objects under retention.

  • false

    Changes to POSIX UIDs, GIDs, and permissions and to object ownership are not allowed for objects under retention.

The default is false.

This property is optional on a PUT request.

This property is not valid for the default namespace.

appendEnabledBoolean

Specifies whether the namespace supports appendable objects. Valid values are:

  • true

    The namespace supports appendable objects.

  • false

    The namespace does not support appendable objects.

The default is false.

This property is optional on a PUT request.

You cannot enable both appendable objects and versioning for a namespace.

This property is not valid for the default namespace.

Note: The appendable-object feature provides snaplock volume support for third-party backup solutions. Do not enable this feature unless you have been explicitly told to do so.

atimeSynchronization EnabledBoolean

Specifies whether atime synchronization with retention settings is enabled for the namespace. Valid values are:

  • true

    Atime synchronization is enabled.

  • false

    Atime synchronization is not enabled.

The default is false.

This property is optional on a PUT request.

This property is not valid for the default namespace.

authAndAnonymous MinimumPermissionsList

Lists the minimum data access permissions for all unauthenticated users of the namespace. Authenticated users also have these permissions when the value of the authUsersAlways-GrantedAllPermissions property is true.

Valid values for permissions are:

  • BROWSE
  • DELETE
  • PURGE
  • READ
  • READ_ACL
  • WRITE
  • WRITE_ACL

The default is no permissions.

These values are not case sensitive.

This property is optional on a PUT request.

The set of permissions specified in the request body replaces the current set of minimum permissions for all users. To remove all the permissions for all users, specify an empty list.

If the set of permissions includes PURGE, delete permission is enabled automatically. If the set of permissions includes READ, browse permission is enabled automatically.

This property is not valid for the default namespace.

authMinimum PermissionsList

Lists the minimum data access permissions for authenticated users of the namespace. Valid values for permissions are:

  • BROWSE
  • DELETE
  • PURGE
  • READ
  • READ_ACL
  • WRITE
  • WRITE_ACL

The default is no permissions.

These values are not case sensitive.

This property is optional on a PUT request.

The set of permissions specified in the request body replaces the current set of permissions for authenticated users. To remove all the permissions for authenticated users, specify an empty list.

If the set of permissions includes PURGE, delete permission is enabled automatically. If the set of permissions includes READ, browse permission is enabled automatically.

This property is not valid for the default namespace.

authUsersAlwaysGranted AllPermissionsBoolean

Specifies whether users have the minimum data access permissions specified by the authAndAnonymous-MinimumPermissions property in addition to the minimum data access permissions specified by the authMinimumPermissions property when using a protocol that requires authentication. Valid values are:

  • true

    Users have the minimum data access permissions specified by both properties when using a protocol that requires authentication.

  • false

    Users have only the minimum data access permissions specified by the authMinimum-Permissions property when using a protocol that requires authentication.

The default is true.

This property is optional on a PUT request.

This property is not valid for the default namespace.

creationTimeString

Specifies the date and time at which the namespace was created, in this ISO 8601 format:

yyyy-MM-ddThh:mm:ssZ

Z represents the offset from UTC, in this format:

(+|-)hhmm

For example:

2017-02-09T19:44:03-0500

This property is not valid on a PUT or POST request. It is returned only by a verbose GET request.
customMetadata IndexingEnabledBoolean

Specifies whether custom metadata indexing is enabled for the namespace. Valid values are:

  • true

    Custom metadata indexing is enabled.

  • false

    Custom metadata indexing is disabled.

The default is false.

This property is optional on a PUT request.

You can set this property to true only while indexing is enabled for the namespace.

Disabling custom metadata indexing for the namespace automatically disables full custom metadata indexing.

customMetadata ValidationEnabledBoolean

Specifies whether custom metadata XML checking is enabled for the namespace. Valid values are:

  • true

    When custom metadata is added to an object in the namespace, HCP checks whether the custom metadata is well-formed XML.

  • false

    When custom metadata is added to an object in the namespace, HCP does not check whether the custom metadata is well-formed XML.

The default is false.

This property is optional on a PUT request.
descriptionString

Specifies a description of the namespace. This description is optional. The default is the description specified by the namespace defaults for the tenant.

To remove a description from an existing namespace, specify the description property with no value.

This property is optional on a PUT request.
dplString

Deprecated. Namespace DPL is now a service plan function.

This property is ignored on a PUT or POST request. In response to a GET request, the value of this property is always Dynamic.

enterpriseModeBoolean

Specifies the namespace retention mode. Valid values are:

  • true

    The namespace is in enterprise mode.

  • false

    The namespace is in compliance mode.

The default is the retention mode specified by the namespace defaults for the tenant.

This property is optional on a PUT request.

You can set the value of this property to false only if the owning tenant is allowed to set the retention mode for its namespaces.

In enterprise mode, privileged deletes are allowed, retention class durations can be shortened, and retention classes can be deleted. In compliance mode, these activities are not allowed.

The value of this property can be changed from true to false but not from false to true.

fullyQualifiedNameStringSpecifies the fully qualified hostname of the namespace.This property is not valid on a PUT or POST request. It is returned only by a verbose GET request.
hardQuotaString

For an HCP namespace, specifies the total amount of space allocated to the namespace. This is the space available for storing objects, including object data, metadata, and the redundant data required to satisfy the namespace service plan.

Valid values are decimal numbers with up to two places after the period, followed by a space, followed by MB, GB, or TB (for example, 1.25 TB). The minimum value is 1 (one) for GB and .01 for TB. The maximum value is the amount of space the tenant has available to allocate to its namespaces. The default is the hard quota specified by the namespace defaults for the tenant.

This property is optional on a PUT request.

This property is not valid for the default namespace.

hashSchemeString

Specifies the cryptographic hash algorithm for the namespace. Valid values are:

  • MD5
  • SHA-1
  • SHA-256
  • SHA-384
  • SHA-512
  • RIPEMD-160

These values are case sensitive.

The default is the cryptographic hash algorithm specified by the namespace defaults for the tenant.

This property is optional on a PUT request. It is not valid on a POST request and is returned only by a verbose GET request.
idStringSpecifies the system-supplied unique ID for the namespace. HCP generates this ID automatically when you create a namespace.This property is not valid on a PUT or POST request. It is returned only by a verbose GET request.
indexingDefaultBoolean

For an HCP namespace, specifies the default index setting for objects added to the namespaces. Valid values are:

  • true

    New objects are marked for indexing.

  • false

    New objects are not marked for indexing.

The default is true.

This property is optional on a PUT request.

This property is not valid for the default namespace.

indexingEnabledBoolean

Specifies whether indexing is enabled for the namespace. Valid values are:

  • true

    Indexing is enabled.

  • false

    Indexing is disabled.

On a PUT request, the default is true if the searchEnabled property is set to true in the same request; otherwise, the default is false.

This property is optional on a PUT request.

You can set this property to true only while search is enabled for the namespace.

Disabling indexing for the namespace automatically disables custom metadata indexing.

isDplDynamicBoolean

Deprecated. Namespace DPL is now a service plan function.

This property is not valid on a PUT or POST request. In response to a GET request, the value of this property is always true.

mqeIndexingTimestampString

Specifies the date and time before which objects are guaranteed to have been indexed by the metadata query engine, in this ISO 8601 format:

yyyy-MM-ddThh:mm:ssZ

Z represents the offset from UTC, in this format:

(+|-)hhmm

For example:

2017-02-09T19:44:03-0500

This property is not valid on a PUT or POST request. It is returned only by a verbose GET request.
multipartUploadAuto AbortDaysInteger

For an HCP namespace, specifies the number of days mutlipart uploads can remain incomplete before they are automatically aborted. Valid values are integers in the range zero through 180. The default is 30.

A value of zero means multipart uploads are never automatically aborted.

This property is optional on a PUT request.

This property is not valid for the default namespace.

nameString

Specifies the name of the namespace. HCP derives the hostname for the namespace from this name. The hostname is used in URLs for access to the namespace.

In English, the name you specify for a namespace must be from one through 63 characters long and can contain only alphanumeric characters and hyphens (-) but cannot start or end with a hyphen. In other languages, because the derived hostname cannot be more than 63 characters long, the name you specify may be limited to fewer than 63 characters.

Namespace names cannot contain special characters other than hyphens and are not case sensitive. White space is not allowed.

Namespace names cannot start with xn-- (that is, the characters x and n followed by two hyphens).

Namespace names must be unique for the owning tenant. Different tenants can have namespaces with the same name.

You can reuse namespace names that are not currently in use. So, for example, if you delete a namespace, you can give a new namespace the same name as the one the deleted namespace had.

The name of the default namespace is always Default.

This property is required on a PUT request.

The namespace name is used in the URL for access to the namespace.

You can change the namespace name any time after you create the namespace, except while the S3 compatible, CIFS, or NFS protocol is enabled for the namespace. However, when you change the name, the URL for the namespace may change as well.

optimizedForString

For an HCP namespace, specifies whether the namespace is optimized for cloud protocols only or optimized for all namespace access protocols. Valid values are:

  • CLOUD

    Optimizes the namespace for cloud protocols only

  • ALL

    Optimizes the namespace for all namespace access protocols

The default is specified by the namespace defaults for the tenant.

These values are not case sensitive.

This property is optional on a PUT request.

You can set this property to ALL on a POST request only if the namespace already does not allow erasure coding or the allowErasureCoding property is set to false in the same request.

This property is not valid for the default namespace

ownerString

For an HCP namespace, specifies the namespace owner. Valid values are:

  • If the owner has an HCP user account, the username for that account.
  • If the owner has an AD user account, the account username along with the name of the AD domain in which the account is defined, in this format: username@ad-domain-name

If the namespace doesn’t have an owner, this property has no value.

This property is optional on a PUT request.

If this property is included on a PUT or POST request with a value that identifies an AD user account, the request must also include the ownerType property with a value of EXTERNAL.

In response to a GET request, if the owner is an AD user and HCP cannot communicate with AD or cannot find the user account in AD, the value of this property is the security ID (SID) for the AD user account.

This property is not valid for the default namespace.

ownerTypeString

For an HCP namespace, specifies the type of the user account that identifies the object owner. Valid values are:

  • LOCAL

    The user account is defined in HCP.

  • EXTERNAL

    The user account is defined in AD.

The default is LOCAL.

These values are not case sensitive.

If the namespace doesn’t have an owner, this property has no value.

This property is optional on a PUT request.

You can specify a value for this property on a PUT or POST request only if you specify a value for the owner property in the same request.

This property is not valid for the default namespace.

readFromReplicaBoolean

Specifies whether read from replica is enabled for the namespace.

Valid values are:

true — Read from replica is enabled.

false — Read from replica is disabled.

On a PUT request, the default is true if replicationEnabled is set to true in the same request; otherwise, the default is false.

This property is optional on a PUT request. You can set the value of this property to true on a PUT request only if, for an HCP namespace, the replicationEnabled property is set to true in the same request or, for the default namespace, the HCP system supports replication.

On a POST request, you can set the value for this property to true for an HCP namespace only if the namespace is already selected for replication or the replicationEnabled property is set to true in the same request. You can set the value for this property to true for the default namespace only if the HCP system supports replication.

This property is not returned by any GET request for an HCP namespace that is not selected for replication. This property is not returned by any GET request for the default namespace if the HCP system does not support replication.

replicationEnabledBoolean

For an HCP namespace, specifies whether the namespace is selected for replication. Valid values are:

true — The namespace is selected for replication.

false — The namespace is not selected for replication.

The default is the replication setting specified by the namespace defaults for the tenant.

This property is optional on a PUT request.

You can set the value of this property to true only if replication is enabled for the owning tenant.

If the HCP system does not support replication, this property is not returned by any GET request.

This property is not valid for the default namespace. If the HCP system supports replication, replication is automatically enabled for that namespace.

replicationTimestampString

Specifies the oldest change time for objects and configuration changes not yet replicated or recovered from the namespace, as applicable, in this format:

yyyy-MM-ddThh:mm:ssZ

Z represents the offset from UTC, in this format:

(+|-)hhmm

For example:

2012-02-27T14:32:19-0500

This property is not valid on a PUT or POST request. It is returned only by a verbose GET request and only when these conditions are true:

•The namespace is selected for replication.

•The tenant that owns the namespace is included in a replication link.

searchEnabledBoolean

Specifies whether search is enabled for the namespace. Valid values are:

  • true

    Search is enabled.

  • false

    Search is disabled.

The default is the search setting specified by the namespace defaults for the tenant.

This property is optional on a PUT request.

You can set the value of this property to true only if the owning tenant is allowed to enable search for its namespaces.

Disabling search after it has been enabled:

  • Automatically disables indexing for the namespace.
  • Removes objects in the namespace from the metadata query engine index. If you subsequently reenable search for the namespace, the namespace must be reindexed from scratch.
  • Deletes the list of excluded annotations for the namespace.
  • Deletes all associations the namespace has with any content classes.
servicePlanStringSpecifies the service plan associated with the namespace. Valid values are names of existing service plans. The default is the service plan specified by the namespace defaults for the tenant.This property is valid on a PUT or POST request and returned by a GET request only if the owning tenant is allowed to select service plans for its namespaces. If valid, this property is optional on a PUT request.

serviceRemoteSystem

Requests

Boolean

Specifies whether HCP can service HTTP requests against the namespace that are redirected from other HCP systems. Valid values are:

  • true

    HCP can service requests against the namespace that are redirected from other systems.

  • false

    HCP cannot service requests against the namespace that are redirected from other systems.

The default is true.

This property is optional on a PUT request.
softQuotaIntegerFor an HCP namespace, specifies the percentage point at which HCP notifies the tenant that free storage space for the namespace is running low. Valid values are integers in the range ten through 95. The default is the soft quota specified by the namespace defaults for the tenant.

This property is optional on a PUT request.

This property is not valid for the default namespace.

tagsList

Associates zero, one, or more tags with the namespace. Each tag can be from one through 64 characters long and can contain any valid UTF-8 characters except commas (,). White space is allowed.

Tags are not case sensitive.

This property is optional on a PUT request.

For an existing namespace, the set of tags specified in the request body replaces the set of tags currently associated with the namespace. To remove all tags, specify an empty set.

In XML, the element that identifies each tag is tag. In JSON, the name in the name/value pair that lists the tags is tag.

This property is not valid for the default namespace.

versioningSettings

versioning

Settings

For an HCP namespace, specifies the versioning settings for the namespace.

If this property is omitted on a PUT request, the default is the versioning settings specified by the namespace defaults for the tenant.

This property is optional on a PUT request. If this property is included on a PUT request and the owning tenant is not allowed to set versioning for its namespaces, the value of the enabled property for versioningSettings, if specified, must be false.

This property is not valid on a POST request and is not returned by a GET request. To modify or retrieve the versioning settings for a namespace, use the namespace versioning-Settings resource.

This property is not valid for the default namespace.

You cannot enable versioning for a namespace while the CIFS, NFS, WebDAV, or SMTP protocol or appendable objects are enabled.

Query parameter for restarting indexing

While search is enabled for a namespace, you can restart metadata query engine indexing of the namespace from the time the namespace was created or from a specified date. To do this, you use this query parameter:

resetMQECheckpoint=(mm/dd/yyyy|0)

The value 0 (zero) restarts indexing from the time the namespace was created.

You use the resetMQECheckpoint query parameter with a POST request against the namespace resource.

Here’s a sample POST request that restarts metadata query engine indexing of the accounts-receivable namespace from the time the namespace was created:

curl -k -i -d "<namespace/>" -H "Content-Type: application/xml"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/namespaces/
     accounts-receivable?resetMQECheckpoint=0”
Example

Here’s an XML example of the namespace data type; the properties shown are those that are returned in response to a verbose GET request:

<namespace>
    <aclsUsage>ENFORCED</aclsUsage>
    <authUsersAlwaysGrantedAllPermissions>true
    </authUsersAlwaysGrantedAllPermissions>
    <allowPermissionAndOwnershipChanges>true
    </allowPermissionAndOwnershipChanges>
    <appendEnabled>false</appendEnabled>
    <atimeSynchronizationEnabled>false</atimeSynchronizationEnabled>
    <authMinimumPermissions>
        <permission>BROWSE</permission>
        <permission>READ</permission>
        <permission>WRITE</permission>
    </authMinimumPermissions>
    <creationTime>2017-02-09T15:42:36-0500</creationTime>
    <customMetadataIndexingEnabled>true</customMetadataIndexingEnabled>
    <customMetadataValidationEnabled>true</customMetadataValidationEnabled>
    <description>Created for the Finance department at Example Company by Lee
        Green on 2/9/2017.</description>
    <dpl>Dynamic</dpl>
    <enterpriseMode>true</enterpriseMode>
    <allowErasureCoding>true</allowErasureCoding>
    <fullyQualifiedName>Accounts-Receivable.Finance.hcp.example.com
    </fullyQualifiedName>
    <hardQuota>50 GB</hardQuota>
    <hashScheme>SHA-256</hashScheme>
    <indexingDefault>true</indexingDefault>
    <indexingEnabled>true</indexingEnabled>
    <isDplDynamic>true</isDplDynamic>
    <mqeIndexingTimestamp>2017-02-26T18:11:13-0400</mqeIndexingTimestamp>
    <multipartUploadAutoAbortDays>30</multipartUploadAutoAbortDays>
    <name>Accounts-Receivable</name>
    <optimizedFor>CLOUD</optimizedFor>
    <owner>pblack</owner>
    <ownerType>LOCAL</ownerType>
    <readFromReplica>true</readFromReplica>
    <replicationEnabled>true</replicationEnabled>
    <replicationTimestamp>2017-02-27T06:45:52-0500</replicationTimestamp>
    <searchEnabled>true</searchEnabled>
    <servicePlan>Short-Term-Activity</servicePlan>
    <serviceRemoteSystemRequests>true</serviceRemoteSystemRequests>
    <softQuota>75</softQuota>
    <tags>
        <tag>Billing</tag>
        <tag>lgreen</tag>
    </tags>
    <id>0e774b8d-8936-4df4-a352-b68766b5c287</id>
    <authAndAnonymousMinimumPermissions>
        <permission>BROWSE</permission>
        <permission>READ</permission>
    </authAndAnonymousMinimumPermissions>
</namespace>

namespaceDefaults

The namespaceDefaults data type describes the namespaceDefaults resource.

Properties

The table below describes the properties included in the namespaceDefaults data type.

PropertyDate TypeDescriptionNotes
allowErasureCodingBoolean

Specifies the default setting for whether new namespaces allow erasure coding. Valid values are:

  • true

    The namespace allows erasure coding.

  • false

    The namespace does not allow erasure coding.

The default is false.

This property is valid on a POST request only if the tenant for which you’re specifying namespace defaults is allowed to manage erasure coding for its namespaces.

You can set the value of this property to true on a POST request only if cloud optimization is already set as the default for new namespaces or if the optimizedFor property is set to true in the same request.

This property is returned by a GET request only if the tenant for which you’re specifying namespace defaults is allowed to manage erasure coding for its namespaces.

descriptionString

Specifies the default description for new HCP namespaces. This description is optional. The default is no description.

To remove a description from the namespace defaults, specify the description property with no value.

dplString

Deprecated. Namespace DPL is now a service plan function.

This property is ignored on a POST request. In response to a GET request, the value of this property is always Dynamic.

effectiveDplString

Deprecated. Namespace DPL is now a service plan function.

This property is not valid on a POST request and is returned only by a verbose GET request. In response to a verbose GET request, the value of this property is always Dynamic.

enterpriseModeBoolean

Specifies the default retention mode for new HCP namespaces. Valid values are:

  • true

    The namespace is in enterprise mode.

  • false

    The namespace is in compliance mode.

The default is true.

In enterprise mode, privileged deletes are allowed, retention class durations can be shortened, and retention classes can be deleted. In compliance mode, these activities are not allowed.

This property is valid on a POST request and returned by a GET request only if the tenant for which you’re specifying namespace defaults is allowed to set the retention mode for its namespaces.

hardQuotaString

Specifies the default hard quota for new HCP namespaces.

The hard quota is the total amount of space allocated to the namespace. This is the space available for storing objects, including object data, metadata, and the redundant data required to satisfy the namespace service plan.

Valid values are decimal numbers with up to two places after the period, followed by a space, followed by MB, GB, or TB (for example, 1.25 TB). The minimum value is 1 (one) for GB and .01 for TB. The maximum value is equal to the hard quota for the tenant. The default is 50 GB.

hashSchemeString

Specifies the default cryptographic hash algorithm for new HCP namespaces. Valid values are:

  • MD5
  • SHA-1
  • SHA-256
  • SHA-384
  • SHA-512
  • RIPEMD-160

These values are case sensitive.

The default is SHA-256.

multipartUploadAuto AbortDaysLong

Specifies the default number of days multipart uploads can remain incomplete before they are automatically aborted. Valid values are integers in the range zero through 180. The default is 30.

A value of zero means multipart uploads are never automatically aborted.

optimizedForString

Specifies whether new namespaces are cloud optimized by default. Valid values are:

  • ALL

    The namespace is optimized for all namespace access protocols.

  • CLOUD

    The namespace is optimized for cloud protocols only.

  • DEFAULT

    The protocol optimzation setting for the namespace is determined by the system-level setting.for this property.

The default is DEFAULT.

These values are not case sensitive.

You can set this property to ALL or DEFAULT on a POST request only if new namespaces already disallow erasure coding by default or the allowErasureCoding property is set to false in the same request.
replicationEnabledBoolean

Specifies the default replication setting for new HCP namespaces. Valid values are:

  • true

    The namespace is selected for replication.

  • false

    The namespace is not selected for replication.

The default is false.

This property is valid on a POST request and returned by a GET request only if replication is enabled for the tenant for which you’re specifying namespace defaults.
searchEnabledBoolean

Specifies the default search setting for new HCP namespaces. Valid values are:

  • true

    Search is enabled.

  • false

    Search is disabled.

The default is false.

This property is valid on a POST request and returned by a GET request only if the owning tenant is allowed to enable search for its namespaces.
servicePlanStringSpecifies the default service plan for new HCP namespaces. Valid values are names of existing service plans. The default is the Default service plan.This property is valid on a POST request and returned by a GET request only if the tenant for which you’re specifying namespace defaults is allowed to select service plans for its namespaces.
softQuotaIntegerSpecifies the default soft quota for new HCP namespaces. Valid values are integers in the range ten through 95. The default is 85.
versioningSettings

versioning

Settings

Specifies the default versioning settings for new HCP namespaces.

The default is no versioning.

This property is valid on a POST request and returned by a GET request only if the tenant for which you’re specifying namespace defaults has versioning configuration enabled.
Example

Here’s an XML example of the namespaceDefaults data type:

<namespaceDefaults>
    <description></description>
    <dpl>Dynamic</dpl>
    <effectiveDpl>Dynamic</effectiveDpl>
    <enterpriseMode>true</enterpriseMode>
    <allowErasureCoding>true</allowErasureCoding>
    <hardQuota>75 GB</hardQuota>
    <hashScheme>SHA-256</hashScheme>
    <optimizedFor>CLOUD</optimizedFor>
    <replicationEnabled>true</replicationEnabled>
    <searchEnabled>true</searchEnabled>
    <servicePlan>Short-Term-Activity</servicePlan>
    <softQuota>75</softQuota>
    <versioningSettings>
         <enabled>true</enabled>
         <prune>true</prune>
         <pruneDays>10</pruneDays>
    </versioningSettings>
</namespaceDefaults>

namespacePermission

The namespacePermission data type describes the namespacePermission property of the dataAccessPermissions data type.

Properties

The table below describes the properties included in the namespacePermission data type.

PropertyData TypeDescriptionNotes
namespaceNameStringSpecifies the name of the namespace to which the permissions listed in the permission property provide access.
permissionsList

Lists the permissions associated with the namespace identified by the namespaceName property. Valid values for permissions are:

  • BROWSE
  • CHOWN
  • DELETE
  • PRIVILEGED
  • PURGE
  • READ
  • READ_ACL
  • SEARCH
  • WRITE_ACL
  • WRITE

These values are not case sensitive.

The set of permissions specified in the request body replaces the set of permissions currently associated with the namespace identified by the namespaceName property. To remove all the permissions for a namespace, specify an empty list.

If the set of permissions includes PURGE, delete permission is enabled automatically. If the set of permissions includes READ, browse permission is enabled automatically. If the set of permissions includes SEARCH, browse and read permissions are enabled automatically.

Example

Here’s an XML example of the namespacePermission data type:

<namespacePermission>
    <namespaceName>Accounts-Receivable</namespaceName>
    <permissions>
         <permission>BROWSE</permission>
         <permission>CHOWN</permission>
         <permission>SEARCH</permission>
         <permission>PURGE</permission>
         <permission>WRITE_ACL</permission>
         <permission>DELETE</permission>
         <permission>PRIVILEGED</permission>
         <permission>READ</permission>
        <permission>READ_ACL</permission>
         <permission>WRITE</permission>
    </permissions>
</namespacePermission>

nfsProtocol

The nfsProtocol data type describes the nfs resource for HCPnamespaces.

Properties

The table below describes the properties included in the nfsProtocol data type.

PropertyData typeDescription
enabledBoolean

Specifies whether the NFS protocol is enabled for the namespace. Valid values are:

  • true

    NFS is enabled.

  • false

    NFS is disabled.

The default is false.

gidIntegerSpecifies the default POSIX GID for objects that don’t have an explicit POSIX GID. Valid values are integers greater than or equal to zero. The default is zero.
ipSettingsipSettings

Specifies which IP addresses can access the namespace through the NFS protocol.

uidIntegerSpecifies the default POSIX UID for objects that don’t have an explicit POSIX UID. Valid values are integers greater than or equal to zero. The default is zero.
Example

Here’s an XML example of the nfsProtocol data type:

<nfsProtocol>
    <enabled>true</enabled>
    <gid>0</gid>
    <ipSettings>
         <allowAddresses>
             <ipAddress>192.168.140.10</ipAddress>
             <ipAddress>192.168.140.14</ipAddress>
             <ipAddress>192.168.140.15</ipAddress>
             <ipAddress>192.168.149.0/24</ipAddress>
         </allowAddresses>
    </ipSettings>
    <uid>0</uid>
</nfsProtocol>

protocols

The protocols data type describes the protocols resource for default namespaces.

NoteFor HCPnamespaces, the protocols resource is superseded by the .../protocols/http resource, which has a data type of httpProtocol.
Properties

The table below describes the properties included in the protocols data type.

PropertyData typeDescription
httpEnabledBoolean

Specifies whether the HTTP protocol is enabled for the namespace. Valid values are:

  • true

    HTTP is enabled.

  • false

    HTTP is disabled.

The default is false.

httpsEnabledBoolean

Specifies whether the HTTPS protocol is enabled for the namespace. Valid values are:

  • true

    HTTPS is enabled.

  • false

    HTTPS is disabled.

The default is true.

ipSettingsipSettingsSpecifies which IP addresses can and cannot access the namespace through the HTTP and HTTPS protocols.
Example

Here’s an XML example of the protocols data type:

<protocols>
    <httpEnabled>false</httpEnabled>
    <httpsEnabled>true</httpsEnabled>
    <ipSettings>
     <allowAddresses>
         <ipAddress>192.168.140.10</ipAddress>
             <ipAddress>192.168.140.14</ipAddress>
             <ipAddress>192.168.140.15</ipAddress>
            <ipAddress>192.168.149.0/24</ipAddress>
         </allowAddresses>
        <allowIfInBothLists>false</allowIfInBothLists>
         <denyAddresses>
             <ipAddress>192.168.149.5</ipAddress>
         </denyAddresses>
     </ipSettings>
</protocols>

recipient

The recipient data type describes the recipient property of the recipients data type.

Properties

The table below describes the properties included in the recipient data type.

PropertyData typeDescriptionNotes
addressStringSpecifies a comma-separated list of well-formed email addresses for notification about messages added to the tenant log.This property is required on a POST request.
importanceString

Specifies whether HCP should send email only about important log messages to the specified email addresses or send email about all log messages. Valid values are:

  • ALL

    Send email about all log messages.

  • MAJOR

    Send email only about important log messages.

The default is MAJOR.

These values are not case sensitive.

severityString

Specifies the severity level of the log messages about which to send email. Valid values are:

  • NOTICE

    Send email about log messages with a severity level of notice, warning, or error.

  • WARNING

    Send email about log messages with a severity level of warning or error.

  • ERROR

    Send email only about log messages with a severity level of error.

The default is ERROR.

These values are not case sensitive.

typeString

Specifies the types of log messages about which to send email. Valid values are comma-separated lists of one or more of:

  • GENERAL

    Send email about log messages that do not have a type of security or compliance.

  • SECURITY

    Send email about log messages with a type of security.

  • COMPLIANCE

    Send email about log messages with a type of compliance.

The default is GENERAL.

These values are not case sensitive.

Example

Here’s an XML example of the recipient data type:

<recipient>
    <address>lgreen@example.com, sgold@example.com</address>
    <importance>MAJOR</importance>
    <severity>ERROR</severity>
    <type>GENERAL,SECURITY</type>
</recipient>

recipients

The recipients data type describes the recipients property of the emailNotification data type.

Properties

The table below describes the property included in the recipients data type.

PropertyData typeDescriptionNotes
recipientrecipient

Specifies:

  • One or more email addresses to which HCP sends email about log messages
  • The types of log messages about which HCP sends email to those addresses

Include one instance of this property (up to 25) for each set of email addresses you want in the recipients list for email notification.

The set of recipients specified in the request body replaces the set of recipients currently configured for email notification.

Recipients are added to the Bcc list for each email.

Because each instance of the recipient property can specify multiple email addresses, you can specify a total of more than 25 addresses across all instances of this property. However, if you specify more than 25, HCP sends each email only to an arbitrary 25 of them.

Example

Here’s an XML example of the recipients data type property:

<recipients>
    <recipient>
         <address>lgreen@example.com, sgold@example.com</address>
         <importance>MAJOR</importance>
         <severity>ERROR</severity>
         <type>GENERAL,SECURITY</type>
    </recipient>
    <recipient>
         <address>mwhite@example.com</address>
         <importance>ALL</importance>
         <severity>WARNING</severity>
         <type>COMPLIANCE</type>
    </recipient>
</recipients>

replicationCollisionSettings

The replicationCollisionSettings data type describes the replicationCollisionSettings resource for namespaces.

Properties

The table below describes the properties included in the replicationCollisionSettings data type.

PropertyData typeDescriptionNotes
actionString

Specifies how HCP should handle objects flagged as replication collisions. Valid values are:

  • MOVE

    Move the object to the .lost+found directory in the same namespace.

  • RENAME

    Rename the object in place.

    When renaming an object, HCP changes the object name to object-name.collision.

These values are not case sensitive.

The default is MOVE.

deleteDaysIntegerSpecifies the number of days objects flagged as replication collisions must remain in the namespace before they are automatically deleted. Valid values are integers in the range zero through 36,500 (that is, 100 years). A value of zero means delete immediately.This property is required on a POST request when the value of the deleteEnabled property is true. It is invalid on a POST request when the value of the deleteEnabled property is false.
deleteEnabledBoolean

Specifies whether HCP should automatically delete objects flagged as replication collisions. Valid values are:

  • true

    Automatically delete objects flagged as replication collisions after the number of days specified by the deleteDays property.

  • false

    Do not automatically delete objects flagged as replication collisions.

Example

Here’s an XML example of the replicationCollisionSettings data type property:

<replicationCollisionSettings>
    <action>MOVE</action>
    <deleteDays>10</deleteDays>
    <deleteEnabled>true</deleteEnabled>
</replicationCollisionSettings>

retentionClass

The retentionClass data type describes the retentionClasses resource.

Properties

The table below describes the properties included in the retentionClass data type.

PropertyData typeDescriptionNotes
allowDispositionBoolean

Specifies whether HCP automatically deletes expired objects in the retention class. Valid values are:

  • true

    Automatically delete expired objects.

  • false

    Do not automatically delete expired objects.

This property is required on a PUT request when the value of the retention class is an offset. It is ignored if the value is not an offset.

This property is required on a POST request when the retention class value is being changed to an offset from another type of value.

descriptionString

Specifies a description of the retention class. This description is optional. The default is no description.

To remove a description from an existing retention class, specify the description property with no value.

nameString

Specifies the name of the retention class. Retention class names must be from one through 64 characters long, can contain only alphanumeric characters, hyphens (-), and underscores (_), and are not case sensitive.

The retention class name must be unique for the namespace. Different namespaces can have retention classes with the same name.

This property is required on a PUT request. It is not valid on a POST request and is returned only by a verbose GET request.
valueStringSpecifies the retention class value. Valid values are special values and offsets. This property is required on a PUT request.
Example

Here’s an XML example of the retentionClass data type:

<retentionClass>
    <description>Implements Finance department standard #42 - keep for 10
         years.</description>
    <value>A+10y</value>
    <allowDisposition>true</allowDisposition>
    <name>FN-Std-42</name>
</retentionClass>

searchSecurity

The searchSecurity data type describes the searchSecurity resource for tenants.

Properties

The table below describes the property included in the searchSecurity data type.

PropertyData typeDescription
ipSettingsipSettingsSpecifies which IP addresses can and cannot access the Search Consolefor the tenant.
Example

Here’s an XML example of the searchSecurity data type:

<searchSecurity>
    <ipSettings>
         <allowAddresses>
             <ipAddress>192.168.140.36</ipAddress>
             <ipAddress>192.168.140.109</ipAddress>
         </allowAddresses>
         <allowIfInBothLists>false</allowIfInBothLists>
         <denyAddresses/>
    </ipSettings>
</searchSecurity>

smtpProtocol

The smtpProtocol data type describes the smtp resource for HCPnamespaces.

Properties

The table below describes the properties included in the smtpProtocol data type.

PropertyData typeDescriptionNotes
emailFormatString

Specifies the format for email objects added through the SMTP protocol. Valid values are:

  • .eml
  • .mbox

The default is .eml.

emailLocationString

Specifies the path for the directory in which to store email objects added through the SMTP protocol. This is the path relative to the root of the namespace (that is, rest, data, or fcfs_data). Start and end the path with a forward slash (/), like this:

/email/company_all/

The default is /email/.

Directory names are case sensitive.

If the specified directory does not exist, HCP creates it.
enabledBoolean

Specifies whether the SMTP protocol is enabled for the namespace. Valid values are:

  • true

    SMTP is enabled.

  • false

    SMTP is disabled.

The default is false.

ipSettingsipSettingsSpecifies which IP addresses can and cannot access the namespace through the SMTP protocol.
separateAttachmentsBoolean

Specifies whether HCP should store attachments separately from the email they accompany. Valid values are:

  • true

    Store attachments separately.

  • false

    Do not store attachments separately.

The default is false.

Example

Here’s an XML example of the smtpProtocol data type:

<smtpProtocol>
    <emailFormat>.eml</emailFormat>
    <emailLocation>/finance/email/<emailLocation>
    <enabled>true</enabled>
    <ipSettings>
         <allowAddresses>
             <ipAddress>192.168.45.213</ipAddress>
         </allowAddresses>
         <denyAddresses/>
    </ipSettings>
    <separateAttachments>false</separateAttachments>
</smtpProtocol>

statistics (data type for tenant and namespace statistics resources)

The statistics data type in this section describes the statistics resource for tenants and namespaces.

Properties

The table below describes the properties included in the statistics data type that describes the statistics resource for tenants and namespaces.

PropertyData TypeDescription
customMetadataCountLongSpecifies the number of custom metadata files stored in a given namespace or in all the namespaces owned by a given tenant.
customMetadataSizeLongSpecifies the total number of bytes of custom metadata stored in a given namespace or in all the namespaces owned by a given tenant.
ingestedVolumeLongSpecifies the total size of the stored data and custom metadata, in bytes, before it was added to a given namespace or to all the namespaces owned by a given tenant.
objectCountLong

Specifies the number of objects, including old versions of objects, in a given namespace or in all the namespaces owned by a given tenant.

Each multipart object counts as a single object. Objects that are in the process of being created by multipart uploads are not included in the object count.

The object count does not include object versions that are delete markers.

shredCountLongSpecifies thetotal number of these items waiting to be shredded in a given namespace or in all the namespaces owned by a given tenant: objects, old versions of objects, parts of multipart objects, parts of old multipart versions of objects, replaced parts of multipart uploads, parts of aborted multipart uploads, unused parts of completed multipart uploads, and transient parts created during the processing of certain multipart upload operations.
shredSizeLongSpecifies the total number of bytes of object, object version, and part data and metadata waiting to be shredded in a given namespace or in all the namespaces owned by a given tenant.
storageCapacityUsedLongSpecifies the total number of bytes occupied by stored data in the given namespace or in all the namespaces owned by the given tenant. This includes object data, metadata, and any redundant data required to satisfy the applicable service plans.
Example

Here’s an XML example of the statistics data type that describes the statistics resource for tenants and namespaces:

<statistics>
    <customMetadataCount>5</customMetadataCount>
    <customMetadataSize>3276</customMetadataSize>
    <objectCount>1616</objectCount>
    <shredCount>0</shredCount>
    <shredSize>0</shredSize>
    <storageCapacityUsed>143892480</storageCapacityUsed>
</statistics>

tenant (data type for tenant resource)

The tenant data type in this section describes the tenants resource.

When you create an HCPtenant, you need to specify query parameters that define the initial user account for the tenant. When you create the default tenant, you need to specify query parameters that further define the default namespace.

Properties

The table below describes the properties included in the tenant data type that describes the tenants resource.

PropertyData typeDescriptionNotes
administrationAllowedBoolean

For an HCP tenant, specifies whether system-level users have administrative access to the tenant. Valid values are:

  • true

    System-level users have administrative access to the tenant.

  • false

    System-level users do not have administrative access to the tenant.

The default is false.

This property is not valid for the default tenant.
authenticationTypesString

For an HCP tenant, lists the types of user authentication supported by the tenant. Possible authentication types are:

  • LOCAL

    The tenant supports local authentication by HCP.

  • RADIUS

    The tenant supports remote authentication by RADIUS servers.

  • EXTERNAL

    The tenant supports remote authentication by AD.

This property is not valid on a POST request. It is returned only by a verbose GET request.

In XML, each listed authentication type is the value of an element named authenticationType. In JSON, the name in the name/value pair that lists the authentication types is authenticationType.

This property is not valid for the default tenant.

complianceConfiguration EnabledBoolean

For an HCP tenant, specifies whether the tenant can set the retention mode of the namespaces it owns. Possible values are:

  • true

    The tenant can set the retention mode.

  • false

    The tenant cannot set the retention mode.

This property is not valid on a POST request. It is returned only by a verbose GET request.

This property is not valid for the default tenant.

In enterprise mode, privileged deletes are allowed, retention class durations can be shortened, and retention classes can be deleted. In compliance mode, these activities are not allowed.

creationTimeString

Specifies the date and time at which the tenant was created, in this ISO 8601 format:

yyyy-MM-ddThh:mm:ssZ

Z represents the offset from UTC, in this format:

(+|-)hhmm

For example:

2017-02-09T19:26:32-0500

This property is not valid on a POST request. It is returned only by a verbose GET request.
fullyQualifiedNameStringSpecifies the fully qualified hostname of the tenant.This property is not valid on a POST request. It is returned only by a verbose GET request.
hardQuotaString

For an HCP tenant, specifies the total amount of space available to the tenant for allocation to its namespaces.

Possible values are decimal numbers with up to two places after the period, followed by a space, followed by MB, GB, or TB (for example, 10.25 TB). The minimum value is 1 (one) for GB and .01 for TB.

This property is not valid on a POST request. It is returned only by a verbose GET request.

This property is not valid for the default tenant.

idStringSpecifies the system-supplied unique ID for the tenant. HCP generates this ID automatically when you create a tenant.This property is not valid on a POST request. It is returned only by a verbose GET request.
maxNamespacesPer Userinteger

For an HCP tenant, specifies the maximum number of namespaces that can be owned at one time by any given user.

Valid values are zero through 10,000. The default is 100.

This property is not valid for the default tenant.
nameString

Specifies the name of the tenant. HCP derives the hostname for the tenant from this name. The hostname is used in URLs for access to the tenant and its namespaces.

The name of the default tenant is always Default.

This property is not valid on a POST request. It is returned only by a verbose GET request for an HCP tenant.

This property is not returned by any GET request for the default tenant.

The tenant name is used in the URL for access to the tenant.

namespaceQuotaString

For an HCP tenant, specifies the number of namespaces HCP reserves for the tenant out of the total number of namespaces the system can have. This is also maximum number of namespaces the tenant can own at any given time.

Possible values are:

  • Integers in the range 1 (one) through the current number of namespaces available for allocation. The number of available namespaces is equal to 10,000 minus the number of namespaces currently allocated to HCP tenants, minus the number of namespaces currently owned by HCP tenants without a quota, minus one for the default namespace, if it exists. If any tenants are above quota, the number of excess namespaces is also subtracted from the number of available namespaces.
  • None

This property is not valid on a POST request. It is returned only by a verbose GET request.

This property is not valid for the default tenant.

replicationConfiguration EnabledBoolean

For an HCP tenant, specifies whether the tenant is eligible for replication. Possible values are:

  • true

    The tenant is eligible for replication.

  • false

    The tenant is not eligible for replication.

This property is not valid on a POST request. It is returned only by a verbose GET request.

This property is not valid for the default tenant. If the HCP system supports replication, directories in the default namespace are automatically eligible for replication.

searchConfiguration EnabledBoolean

For an HCP tenant, specifies whether the tenant can enable and disable search for the namespaces it owns. Possible values are:

  • true

    The tenant can enable and disable search for its namespaces.

  • false

    The tenant cannot enable or disable search for its namespaces.

This property is not valid on a POST request. It is returned only by a verbose GET request.

This property is not valid for the default tenant.

snmpLoggingEnabledBoolean

Specifies whether tenant log messages are sent to the SNMP managers specified at the HCP system level. Valid values are:

  • true

    Tenant log messages are sent to SNMP managers.

  • false

    Tenant log messages are not sent to SNMP managers.

The default is false.

softQuotaInteger

For an HCP tenant, specifies the percentage point at which HCP notifies the tenant that free storage space is running low.

Possible values are integers in the range zero through 100.

This property is not valid on a POST request. It is returned only by a verbose GET request.

This property is not valid for the default tenant.

syslogLoggingEnabledBoolean

Specifies whether tenant log messages are sent to the syslog servers specified at the HCP system level. Valid values are:

  • true

    Tenant log messages are sent to syslog servers.

  • false

    Tenant log messages are not sent to syslog servers.

The default is false.

tenantVisibleDescriptionString

Specifies the tenant-level description of the tenant. This description is optional. The default is no description.

To remove a tenant-level description from an existing tenant, specify the tenantVisibleDescription property with no value.

versioningConfiguration EnabledBoolean

For an HCP tenant, specifies whether the tenant's namespaces can have versioning enabled. Possible values are:

  • true

    The tenant's namespaces can have versioning enabled.

  • false

    The tenant's namespaces cannot have versioning enabled.

This property is not valid on a POST request. It is returned only by a verbose GET request.

This property is not valid for the default tenant.

Example

Here’s an XML example of the tenant data type that describes the tenants resource; the properties shown are those that are returned in response to a verbose GET request for an HCP tenant where the request is made using a tenant-level user account that includes the administrator role:

<tenant>
    <administrationAllowed>true</administrationAllowed>
    <authenticationTypes>
        <authenticationType>LOCAL</authenticationType>
        <authenticationType>RADIUS</authenticationType>
    </authenticationTypes>
    <complianceConfigurationEnabled>true</complianceConfigurationEnabled>
    <creationTime>2017-02-09T09:11:17-0500</creationTime>
    <fullyQualifiedName>Finance.hcp.example.com</fullyQualifiedName>
    <hardQuota>100 GB</hardQuota>
    <maxNamespacesPerUser>5</maxNamespacesPerUser>
    <name>Finance</name>
    <namespaceQuota>5</namespaceQuota>
    <replicationConfigurationEnabled>true</replicationConfigurationEnabled>
    <snmpLoggingEnabled>false</snmpLoggingEnabled>
    <searchConfigurationEnabled>true</searchConfigurationEnabled>
    <softQuota>90</softQuota>
    <syslogLoggingEnabled>true</syslogLoggingEnabled>
    <tenantVisibleDescription>Please see Lee Green for any questions about this
        tenant and its namespaces.</tenantVisibleDescription>
    <id>4420f62f-3f63-43ab-a3cd-0bcf1f399daf</id>
    <versioningConfigurationEnabled>true</versioningConfigurationEnabled>
</tenant>

updatePasswordRequest

The updatePasswordRequest data type describes the request to change a password for a system-level user account or a tenant-level user account.

Properties

The table below describes the property included in the updatePasswordRequest data type.

PropertyData typeDescription
newPasswordStringThe new password that you want to set for the system-level user account or tenant-level user account.
Example

Here’s an XML example of the updatePasswordRequest data type:

<updatePasswordRequest>
    <newPassword>End321!</newPassword>
</updatePasswordRequest>

userAccount (tenant level)

The userAccount data type describes the userAccounts resource.

When you create a user account, you use a query parameter to specify the password for the account. You use the same query parameter to change the password for a user account.

Properties

The table below describes the properties included in the userAccount data type.

PropertyData typeDescriptionNotes
allowNamespace ManagementBoolean

Specifies whether the user account has the allow namespace management property. Valid values are:

  • true

    The user account has the allow namespace property.

  • false

    The user account does not have the allow namespace management property.

On a PUT request, the default is true if the roles property includes ADMINISTRATOR in the same request; otherwise, the default is false.

On a POST request, adding ADMINISTRATOR to the roles for the user account automatically enables the allow namespace management property for the account.

Users with the allow namespace management property can use the HCP management and S3 compatible APIs to:

  • Create namespaces
  • List, view and change the versioning status of, and delete namespaces they own
This property is not valid on a PUT request. It is valid on a POST request only if the user making the request has the administrator role.
descriptionString

Specifies the description of the user account. This description is optional. The default is no description.

To remove a description from an existing user account, specify the description property with no value.

This property is valid on a POST request only if the user making the request has the security role.
enabledBoolean

Specifies whether the user account is enabled. Valid values are:

  • true

    The user account is enabled.

  • false

    The user account is disabled.

This property is required on a PUT request. It is valid on a POST request only if the user making the request has the security role.
forcePasswordChangeBoolean

Specifies whether the password for the user account must be changed the next time the account is used to log into the Tenant Management Console. Valid values are:

  • true

    The password must be changed.

  • false

    The password does not need to be changed.

This property is required on a PUT request. It is valid on a POST request and returned by a GET request only if the user making the request has the security role.
fullNameStringSpecifies the full name of the user for whom you’re creating the account. This name must be from one through 64 characters long and can contain any valid UTF-8 characters, including white space.This property is required on a PUT request. It is valid on a POST request only if the user making the request has the security role.
localAuthenticationBoolean

Specifies whether the user account is authenticated locally or by a RADIUS server specified at the HCP system level. Valid values are:

  • true

    The user account is authenticated locally.

  • false

    The user account is authenticated by a RADIUS server.

This property is required on a PUT request. It is not valid on a POST request and is returned only by a verbose GET request.
rolesList

Associates zero, one, or more roles with the user account. Valid values for roles are:

  • ADMINISTRATOR
  • COMPLIANCE
  • MONITOR
  • SECURITY

These values are not case sensitive.

The default is no roles.

This property is valid on a POST request and returned by a GET request only when the user making the request has the security role.

For an existing user account, the set of roles specified in the request body replaces the set of roles currently associated with the user account. To remove all roles, specify an empty set.

In XML, the element that identifies each role is role. In JSON, the name in the name/value pair that lists the roles is role.

userGUIDStringSpecifies the system-supplied globally unique user ID for the user account. HCP generates this ID automatically when you create an account.This property is not valid on a PUT or POST request. It is returned only by a verbose GET request and only when the user making the request has the security role.
userIDInteger

Specifies the system-supplied local user ID for the user account. HCP generates this ID automatically when you create an account.

Local user IDs are unique within an HCP system. These IDs are maintained for backward compatibility but are no longer used for user identification.

This property is not valid on a PUT or POST request. It is returned only by a verbose GET request and only when the user making the request has the security role.
usernameString

Specifies the username for the user account. Usernames must be from one through 64 characters long and can contain any valid UTF-8 characters, including white space, but cannot start with an opening square bracket ([).

Usernames are not case sensitive.

The username for a user account must be unique for the tenant. Different tenants can have user accounts with the same username.

You can reuse usernames that are not currently in use. So, for example, if you delete the account for a user and then create a new account for that user, you can give the user the same username as before.

Tip: Consider using email addresses as user names. This enables users to more easily remember their HCP usernames. It also gives you easy access to email addresses should you need to contact any users.

This property is required on a PUT request. It is valid on a POST request only when the user making the request has the security role.
Query parameter for setting user account passwords

You use the password query parameter to specify the password for a new user account and to change the password for an existing user account. The value of this parameter is the password you want.

Example

Here’s an XML example of the userAccount data type:

<userAccount>
    <allowNamespaceManagement>false</allowNamespaceManagement>
    <description>Compliance officer.</description>
    <enabled>true</enabled>
    <forcePasswordChange>true</forcePasswordChange>
    <fullName>Morgan White</fullName>
    <localAuthentication>true</localAuthentication>
    <roles>
         <role>MONITOR</role>
         <role>COMPLIANCE</role>
    </roles>
    <userGUID>a8ae69dc-e2e3-44a9-aa64-9c142a38ed5d</userGUID>
    <userID>517</userID>
    <username>mwhite</username>
</userAccount>

versioningSettings

The versioningSettings data type describes the versioningSettings resource for namespaces and the versioningSettings property of the namespace and namespaceDefaults data types.

Properties

The table below describes the properties included in the versioningSettings data type.

PropertyData typeDescriptionNotes
daysOnPrimaryInteger

Specifies the number of days old versions of objects must remain in the namespace before they are pruned. Valid values are integers in the range zero through 36,500 (that is, 100 years). A value of zero means prune immediately.

The default is zero.

Deprecated; replaced by the pruneDays property.

If specified on a PUT or POST request, this property has the same function as the pruneDays property. You cannot include both this property and the pruneDays property in the same request.

This property is not returned by any GET request.

daysOnReplicaInteger

Deprecated. The pruneDays property applies to the namespace on all systems on which the namespace exists.

This property is ignored on a PUT or POST request and is not returned by any GET request.

enabledBoolean

Specifies whether versioning is enabled for the namespace. Valid values are:

  • true

    Versioning is enabled.

  • false

    Versioning is disabled.

The default is false.

This property is required on a PUT request to create a namespace and on a POST request to modify namespace defaults if the request includes the versioningSettings property.

You cannot enable versioning for a namespace while the CIFS, NFS, WebDAV, or SMTP protocol or appendable objects are enabled.

keepDeletionRecordsBoolean

Specifies whether HCP should keep records of deletion operations (delete, purge, prune, disposition) that occur in the namespace if the namespace has ever had versioning enabled. Valid values are:

  • true

    Keep records of deletion operations.

  • false

    Do not keep records of deletion operations.

The default is true.

The amount of time for which HCP keeps deletion records is determined by the system configuration.

This property is not valid on a POST request to modify namespace defaults and is not returned by any GET request for namespace defaults.
pruneBoolean

Specifies whether version pruning is enabled for the namespace. Valid values are:

  • true

    Version pruning is enabled for the namespace.

  • false

    Version pruning is disabled for the namespace.

The default is false.

This property is required on a PUT request to create a namespace and on a POST request to modify namespace defaults if the enabled property is set to true.

You cannot include both this property and the pruneOnPrimary property in the same request.

pruneDaysInteger

Specifies the number of days old versions of objects must remain in the namespace before they are pruned. Valid values are integers in the range zero through 36,500 (that is, 100 years). A value of zero means prune immediately.

The default is zero.

This property is required on a PUT request to create a namespace and on a POST request to modify namespace defaults if the prune property is set to true.

You cannot include both this property and the daysOnPrimary property in the same request.

pruneOnPrimaryBoolean

Specifies whether version pruning is enabled for the namespace. Valid values are:

  • true

    Version pruning is enabled for the namespace.

  • false

    Version pruning is disabled for the namespace.

The default is false.

Deprecated; replaced by the prune property.

If specified on a PUT or POST request, this property has the same function as the prune property. You cannot include both this property and the prune property in the same request.

This property is not returned by any GET request.

pruneOnReplicaBoolean

Deprecated. The prune property applies to the namespace on all systems on which the namespace exists.

This property is ignored on a PUT or POST request and is not returned by any GET request.

Example

Here’s an XML example of the versioningSettings data type:

<versioningSettings>
   <enabled>true</enabled>
   <keepDeletionRecords>true</keepDeletionRecords>
   <prune>true</prune>
   <pruneDays>10</pruneDays>
</versioningSettings>

Specifying retention values

These properties require you to specify a retention value:

  • The retentionDefault property of the complianceSettings data type. The value of this property can be a special value, offset, retention class, or fixed date.
  • The minimumRetentionAfterInitialUnspecified property of the complianceSettings data type. The value of this property can be an offset.
  • The value property of the retentionClass data type. The value of this property can be a special value or an offset.
Specifying a special value

To specify a special value as a retention value, use one of these:

  • 0

    Deletion Allowed

    Allows the object to be deleted at any time.

  • -1

    Deletion Prohibited

    Prevents the object from ever being deleted by means of a normal delete operation. If the namespace is in enterprise mode, however, the object can be deleted by means of a privileged delete operation.

  • -2

    Initial Unspecified

    Prevents the object from being deleted but allows its retention setting to be changed.

These values are not case sensitive.

Specifying an offset

To specify an offset as a retention value, use a standard expression that conforms to this syntax:

^A([+-]\d+y)?([+-]\d+M)?([+-]\d+w)?([+-]\d+d)?([+-]\d+h)?([+-]\d+m)?([+-]\d+s)?$

The list below explains this syntax.

  • ^

    Start of the expression

  • $

    End of the expression

  • ( )

    Sequence of terms treated as a single term

  • ?

    Indicator that the preceding term is optional

  • [ ]

    Group of alternatives, exactly one of which must be used

  • +

    Plus

  • -

    Minus

  • A

    The time at which the object was added to the repository

  • /d+

    An integer in the range 0 (zero) through 9,999

  • y

    Years

  • M

    Months

  • W

    Weeks

  • D

    Days

  • h

    Hours

  • m

    Minutes

  • s

    Seconds

The time measurements included in an expression must go from the largest unit to the smallest (that is, in the order in which they appear in the syntax). These measurements are case sensitive. You can omit measurements that have value of zero.

Here are some offset examples:

A+100y
A+20d-5h
A+2y+1d
Specifying a retention class

To specify a retention class as a retention value, use this format:

C+retention-class-name

For example, if the name of the retention class is HlthReg-107, specify the property value as:

C+HlthReg-107

The retention class you specify must already exist.

Specifying a fixed date

To specify a fixed date as a retention value, you can use either of these formats:

  • Time in seconds since January 1, 1970, at 00:00:00. For example:
    1514678400

    The calendar date that corresponds to 1514678400 is Sunday, December 31, 2017, at 00:00:00 EST.

  • Date and time in this ISO 8601 format:
    yyyy-MM-ddThh:mm:ssZ

    Z represents the offset from UTC and is specified as:

    (+|-)hhmm

    For example: 2017-12-31T00:00:00-0500

If you specify certain invalid dates, HCP automatically adjusts the value to make a real date. For example, if you specify a default retention setting of 2017-11-33T00:00:00-0500, which is three days past the end of November, objects added to the namespace get a retention setting of 2017-12-03T00:00:00-0500.

 

  • Was this article helpful?