From 1a4090aa3b4f832dc0e225d7134bc561c95a159f Mon Sep 17 00:00:00 2001 From: Miguel Estrada Date: Tue, 5 Jun 2018 16:50:47 -0400 Subject: [PATCH 1/3] Create files_experimental.md --- guides/files_experimental.md | 148 +++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 guides/files_experimental.md diff --git a/guides/files_experimental.md b/guides/files_experimental.md new file mode 100644 index 0000000..c83735f --- /dev/null +++ b/guides/files_experimental.md @@ -0,0 +1,148 @@ +--- +copyright: 'Copyright IBM Corp. 2017' +link: 'files-guide' +is: 'experimental' +--- + + +# Files in IBM Watson Work Services + +**Note: This documentation and underlying APIs and structures ARE subject to change** + +## Concepts + +- Files can exist in a number of external repositories with various degrees of integration capabilities +- IBM Watson Work Services _provides_ a default Files repository which we will which we will refer to as **Files** in this document +- Files are related to the rest of the object model in Watson Work Services by virtue of two connecting points: + - a reference to them as part of markdown in a conversation message + - an annotation of type `File` to a conversation message +- Typically a conversation message contains both, a reference in its content markdown and an annotation +- Uploading a file is simple, just use the REST endpoint described [here](https://developer.watsonwork.ibm.com/docs/api-reference/files) +- Downloading files require that either you already have the URL which is: + - given back to you as a result of an upload operation + - derived from a File reference obtained by using GraphQL queries into the Watson Work Services data model + - derived from a File reference provided in real time via webhook callback due to Watson Work Services model change + +## Using GraphQL to inspect model + +### Conversation message content + +Use a GraphQL query to obtain the message(s) content properties and parse it looking for markdown with format: + +`<$file|FILE_REFID|FILE_NAME|WIDTHxHEIGHT>` + +Where: +`FILE_REFID` is the actual File Reference Id which is needed to obtain a download URL +`FILE_NAME` is the intended file name +`WIDTH` and `HEIGHT`specify the size of the image in case the file content is of type: `image/jpeg` + +Example: +`<$file|ibm0@default@578cf829e4b0c3e87919a2b1@file-bf17cbc5-a5ec-4ecf-940a-b8be4822e49e|Social-9.jpg|1024x768>` + + +### Conversation message annotations + +Use a GraphQL query to obtain the message(s) annotations of either type `generic` or type `file` + +#### generic annotations + +Similar to the above message created, but instead obtain the message content from the event element called `text` + +#### file annotations + +The file annotation is identified with an annotation `type` of `file` and will contain the FILE_REFID identified above in the element `fileid` of the annotation payload + +As a reference, here is the File annotation payload which is JSON in stringified format: + +`"{\"type\":\"file\",\"annotationId\":\"5a8cbcede4b0de791d72efef\",\"type\":\"file\",\"version\":\"1.0\",\"created\":1519172845653,\"createdBy\":\"toscana-service-storage-client-id\",\"updated\":1519172845653,\"updatedBy\":\"toscana-service-storage-client-id\",\"tokenClientId\":\"toscana-service-storage-client-id\",\"fileId\":\"ibm0@default@578cf829e4b0c3e87919a2b1@file-bf17cbc5-a5ec-4ecf-940a-b8be4822e49e\",\"name\":\"Social-9.jpg\",\"size\":139512,\"contentType\":\"image/jpeg\",\"width\":1024,\"height\":768,\"messageRefId\":null}"` + +Here is the same information in JSON format: + +``` +{ + "type": "file", + "annotationId": "5a8cbcede4b0de791d72efef", + "type": "file", + "version": "1.0", + "created": 1519172845653, + "createdBy": "toscana-service-storage-client-id", + "updated": 1519172845653, + "updatedBy": "toscana-service-storage-client-id", + "tokenClientId": "toscana-service-storage-client-id", + "fileId": "ibm0@default@578cf829e4b0c3e87919a2b1@file-bf17cbc5-a5ec-4ecf-940a-b8be4822e49e", + "name": "Social-9.jpg", + "size": 139512, + "contentType": "image/jpeg", + "width": 1024, + "height": 768, + "messageRefId": null +} +``` + +## Using Webhook events + +### Message Created + +Obtain the message content element from the event data and refer to above information in the inspecting the model section as it is essentially the same approach. + +### Annotation Added + +#### Generic Annotation + +Obtain the value of `text` element from the annotation payload and refer to the information above in the inspecting the model section + +#### File Annotation + +Obtain the value of `fileid` element of the annotation payload and refer to the information above in the inspecting the model section + +## Deriving a File download URL from a Watson Work Services File reference + +This is a three step process: +1. download metadata about the file and decide which method to use to obtain a download URL +2. use either redirect or non-redirect URL to obtain a download URL which will expire in 10 minutes and which should not be considered a permanent URL +3. download the file contents using download URL obtained from step 2 + +#### Step 1. Download File Metadata + +`https://api.watsonwork.ibm.com/files/api/v1/files/file/` + +Where `` is the File identifier obtained via model inspection or webhook notification described earlier + +Example: +https://api.watsonwork.ibm.com/files/api/v1/files/file/ibm0@default@578cf829e4b0c3e87919a2b1@file-bf17cbc5-a5ec-4ecf-940a-b8be4822e49e + +This yields a JSON structure as follows: + +``` +{ + "entries": [ + { + "id": "ibm0@default@578cf829e4b0c3e87919a2b1@file-bf17cbc5-a5ec-4ecf-940a-b8be4822e49e", + "name": "Social-9.jpg", + "size": 139512, + "urls": { + "metadata": "https://api.watsonwork.ibm.com/files/api/v1/files/file/ibm0@default@578cf829e4b0c3e87919a2b1@file-bf17cbc5-a5ec-4ecf-940a-b8be4822e49e", + "noredirect_download": "https://api.watsonwork.ibm.com/files/api/v1/files/file/ibm0@default@578cf829e4b0c3e87919a2b1@file-bf17cbc5-a5ec-4ecf-940a-b8be4822e49e/content/noredirect/Social-9.jpg", + "redirect_download": "https://api.watsonwork.ibm.com/files/api/v1/files/file/ibm0@default@578cf829e4b0c3e87919a2b1@file-bf17cbc5-a5ec-4ecf-940a-b8be4822e49e/content/redirect/Social-9.jpg" + }, + "created": 1519172842000, + "createdBy": "97a45340-8f0a-1028-803c-db07163b51b2", + "contentType": "image/jpeg", + "scanStatus": "PASS", + "lastScan": 1519172841111 + } + ], + "total_count": 1 +} +``` + +#### Step 2. Decide which method to use to obtain Download URL: + +- `noredirect_download` is a URL which will return http status 204 with header `X-Content-Location` an actual URL to the download location which will be valid for only 10 minutes per the `Expires` param on the URL +- `redirect_download` is a URL which will return http status 302 with header `Location` an actual URL to the download location which will be valid for only 10 minutes per the `Expires` param on the URL + +#### Step 3. Use Download URL + +Note that the download URLs obtained in either `X-Content-Location` or `Location` ** are not to be considered stable and can change ** and for this reason it is a moot point to even describe the URL format in documentation + + From 9a978565d711450d57cd29198d11d4d9a6d36668 Mon Sep 17 00:00:00 2001 From: Miguel Estrada Date: Tue, 21 Aug 2018 15:55:25 -0400 Subject: [PATCH 2/3] Update files_experimental.md --- guides/files_experimental.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/files_experimental.md b/guides/files_experimental.md index c83735f..a93757f 100644 --- a/guides/files_experimental.md +++ b/guides/files_experimental.md @@ -7,7 +7,7 @@ is: 'experimental' # Files in IBM Watson Work Services -**Note: This documentation and underlying APIs and structures ARE subject to change** +**Note: OBSOLETE. Need to update to GraphQL variant. This documentation and underlying APIs and structures ARE subject to change** ## Concepts From 5b0b1b4a39bdba3d73fe7d0202a51d9d94912698 Mon Sep 17 00:00:00 2001 From: Miguel Estrada Date: Tue, 11 Sep 2018 10:38:46 -0400 Subject: [PATCH 3/3] Update files_experimental.md --- guides/files_experimental.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/files_experimental.md b/guides/files_experimental.md index a93757f..ccc8acd 100644 --- a/guides/files_experimental.md +++ b/guides/files_experimental.md @@ -12,7 +12,7 @@ is: 'experimental' ## Concepts - Files can exist in a number of external repositories with various degrees of integration capabilities -- IBM Watson Work Services _provides_ a default Files repository which we will which we will refer to as **Files** in this document +- IBM Watson Work Services _provides_ a default Files repository which we will refer to as **Files** in this document - Files are related to the rest of the object model in Watson Work Services by virtue of two connecting points: - a reference to them as part of markdown in a conversation message - an annotation of type `File` to a conversation message