Updating a file
Added by IBM contributorIBM | Edited by IBM contributorElizabeth Bowling on November 9, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

Update a file in your file collection.
You can use one or more of these headers.

You can use one or more of these input parameters with the request. Separate multiple parameters with an ampersand (&).

A file consists of both the information about the file, which is also known as metadata, and the binary data that the file contains. Pass binary data as the input of the request. To update the metadata associated with the file, pass new values for the document elements using input parameters.

Authentication

This method requires authentication. In order to modify a document, the currently authenticated user must be owner of the user library containing the document, an administrator, or have been shared with as an editor. 

Input
Method URI Description
PUT /files/{auth}/api/myuserlibrary/document/{document-id}/media Determine the resource address in either of the following ways:
Value of the href attribute of the <link rel="edit-media"> element in the file's Document Atom entries.
Construct the address using the following URL:/files/{auth}/api/myuserlibrary/document/{document-id}/mediawhere {document-id} is the <td:uuid> or <td:label> element of the document entry.
PUT /files/{auth}/api/library/{library-id}/document/{document-idOrLabel}/entry Update the document specified by its uuid or its unique label.
PUT /files/{auth}/api/library/{library-id}/draft/{draft-id}/entry Update the specified draft.
Name Type Optional Description
document-id
string No {document-id} is the <td:uuid> or <td:label> element of the document entry.
auth
enumerated No The authorization protocol being used by your application to access Connections Cloud.
Authorized values:
  • basic
  • oauth
Name Type Optional Description
commentNotification
enumerated Yes String. Specifies whether you want to get an email notification when someone adds or updates a comment on a file. Options are on or off.
Authorized values:
  • on
  • off
created
string Yes Date to use as the creation date of the file. Specify the time in the number of milliseconds since January 1, 1970, 00:00:00 GMT time. This value can be set by the user, and defaults to the current system time on the server.
identifier
string Yes Indicates how the document is identified in the {document-id} variable segment of the web address. By default, look up is performed with the expectation that the URL contains the value from the <td:uuid> element of a File Atom entry. Specify "label" if the URL instead contains the value from the <td:label> element of a File Atom entry.
includePath
boolean Yes Specifies whether to include the file path information. This parameter takes a Boolean value of either true or false. If true, adds an entry extension <td:path> showing the path to the object.
mediaNotification
enumerated Yes String. Specifies whether the person updating the file wants to get an email notification when someone subsequently updates the file. Options are on or off.
Authorized values:
  • on
  • off
modified
string Yes Date to use as the last modified date of the file. Specify the time in the number of milliseconds since January 1, 1970, 00:00:00 GMT time. This value can be set by the user, and defaults to the current system time on the server.
recommendation
enumerated Yes Specifies whether the person updating the document recommends the document. This parameter takes a Boolean value of either on or off. The default is off.
Authorized values:
  • on
  • off
removeTag
string Yes Removes the specified tag. Use it multiple times to remove multiple tags or set it equal to null to remove all tags.
sendNotification
boolean Yes Specified whether notifications should be sent about this update. This parameter takes a Boolean value of either true or false.
Default is true.
sharePermission
enumerated Yes Defines the level of permission that the people listed in the sharedWith parameter should have to the file. Only applicable if the sharedWith parameter is passed. Permission level options are Edit or View.
Authorized values:
  • Edit
  • View
shareSummary
string Yes Text. Explanation of the share.
shareWith
string Yes User ID of the user to share the content with. This parameter can be applied multiple times. Supports multivalue.
tag
string Yes String. Keyword that helps to classify the file. This parameter can be applied multiple times if multiple tags are passed. Supports multivalue. If this parameter and the removeTag parameter pass the same value, the removeTag parameter gets precedence.
visibility
enumerated Yes String. Specifies who can see the file. A public file is visible to all users and can be shared by all users.
Authorized values:
  • private
  • public
  • null
description
string Yes Description of the file to be created.
draft
enumerated Yes Passing true indicates that the resource is persisted as a Draft instead of a Document. Passing false will not cause a draft to be submitted/published.
Default value is false.
Authorized values:
  • true
  • false
doctype
string Yes The document type to be applied to the resource. If specified, this will take precedence over the documenttype included in the ATOM entry. The UUID of the document type can be set by the user, and defaults to the type identified by the system.
submit
enumerated Yes Specifies if the resource should be submitted for approval, if approval is enabled on the document. If approval is not enabled, the Document or Draft is simply checked in.
The default value is false.
Authorized values:
  • true
  • false
lock
enumerated Yes Specifies if the resource needs to be locked on the server prior to update.
The default value is false.
Authorized values:
  • true
  • false
propagate
enumerated Yes True specifies that a private file can be shared by other users.
False specifies that a private file can be shared only by the file's owner.
True is considered the default for public files until the file is made private again.
The default value is true.
Authorized values:
  • true
  • false
sendEmail
enumerated Yes Specifies if an email notification will be sent when sharing to the specified user. Only take effect when shareWith is not null.
Default value is true.
Authorized values:
  • true
  • false
includeLocked
enumerated Yes if true, adds an entry extension <td:locked> showing if document is locked.
Default value is false.
Authorized values:
  • true
  • false
includeLockOwner
enumerated Yes If true, adds an entry extension <td:lockOwner> showing who holds the lock.
Default value is false.
Authorized values:
  • true
  • false
isExternal
enumerated Yes Indicate whether the file is external or internal. This attribute is used for multi-tenancy deployment or single-tenancy where visitor model is enabled. This is optional. If it is not specified, server will choose default value based on policy.
Authorized values:
  • true
  • false
createVersion
enumerated Yes Indicates whether to create a version of the document as it is saved (many implementations will choose to only respect this param if the file content has changed).
Default value is true.
Authorized values:
  • true
  • false
changeSummary
string Yes Change summary of the new version.
restrictedVisibility
enumerated Yes Indicates if this document's visibility is restricted to private only. A value of 'true' means the document can only be private. False means the value can be any valid visibility value. No change if not passed.
Default value is false.
Authorized values:
  • true
  • false
  • null
favorite
enumerated Yes Specify if this document will be added into or removed from favorite.
Default value is false.
Authorized values:
  • true
  • false
lockType
enumerated Yes String. Lock or unlock the document on update. Set to hard to lock the document. Set to none to unlock.
Authorized values:
  • none
  • hard
baseTimestamp
date Yes Set by client to indicate the last modified time of the document upon which client makes change. This information is used by server to determine whether to generate new version even if replace is true and mark the new version as conflict. This need auto-versioning to be enabled.
updatedVia
enumerated Yes String. Indicates which channel the document is updated in. If not specified, files would be taken as default value, which means it is updated via Connections Files.
Authorized values:
  • files
  • verse
  • docs.auto
  • docs.manual
  • filesync
addToCollection
string Yes Change the access permission of the listed collections to read. If the permission of one collection is already read or if the document is not a child of that collection, no change is made for that collection.
Value is the list of collection UUIDs to read.
addToCollectionWithEdit
string Yes Change the access permission of the listed collections to edit. If the permission of one collection is already edit or if the document is not a child of that collection, no change is made for that collection.
Value is the list of collection UUIDs to read.
Name Type Optional Description
Content-Type
string Yes Used to specify the mime type for the content being sent to the server. If the collection does not support the specified content type, the server returns HTTP response code 415 (Unsupported media type). When a media resource is posted, the mime-type of the resource is set to this value if it is provided. Otherwise, the mime-type of the extension of the Slug header is used. A Content-Type that is an empty string, whitespace only, or equal to "unknown/unknown" is considered to be not-specified.
Content-Language
string Yes Specifies the language of the content being sent to the server. All contents are handled using UTF-8 encoding on the server.
Content-Length
string Yes Specifies the content length when sending media content.
X-Update-Nonce
string Yes String. Represents a unique data string generated by the server upon request that you can provide to secure the request. See Getting a nonce key for information about how to request the data string.
Authorization
enumerated No The authentication mechanism selected by your application to access the API.
Basic is the Base64 encoding of the IBM Connections Cloud username and password: Base64(username:password). For example, Base64(twatson@us.ibm.com:password).
Bearer is the oauth 2.0 access token that is generated when the user grants your application access to IBM Connections Cloud services.
See the reference topic "OAuth 2.0 APIs for web server flow" for more information.
Authorized values:
  • bearer
  • basic
If-Match
string Yes Support conditional PUT.
X-Method-Override
enumerated Yes Tunnel a 'PUT' request over HTTP POST.
Authorized values:
  • PUT
Output
Content Type: application/atom+xml
Code Description
200
Indicates that the file entry was successfully created. If an error occurs, this header contains one of the error codes.
401
Unauthorized.
403
Forbidden.
404
Not Found.
References
Examples
PUT /files/basic/api/myuserlibrary/document/ced0378d-4dda-427c-bdf6-e71e56863bca/entry?tag=addTagTest