Importing files added details to wix-media-backend

* DocWorks for wix-media-manager-backend - 3 changes detected, but 1 issue detected
changes:
Service wix-media-backend.MediaManager operation importFile has changed description
Service wix-media-backend.MediaManager operation upload has changed description
Service wix-media-backend.MediaManager message MetadataOptions member context has changed doc

issues:
Operation upload has an unknown param type Buffer (upload.js (1))

* Added importing and uploading files article

* Small changes following technical review

* Changes to align with wix-media.v2

* Apply suggestions from code review

Co-authored-by: adamfri <[email protected]>

* DocWorks for wix-media-manager-backend - 1 change detected, but 1 issue detected
changes:
Service wix-media-backend.MediaManager message MetadataOptions member context has changed doc

issues:
Operation upload has an unknown param type Buffer (upload.js (1))

---------

Co-authored-by: adamfri <[email protected]>

wix-media-manager-backend/wix-media-backend/MediaManager.service.json

@@ -136,8 +136,7 @@
         "extra":
           {  } },
       { "name": "downloadFolder",
-        "labels":
-          [ "changed" ],
+        "labels": [],
         "nameParams": [],
         "params":
           [ { "name": "folderId",
@@ -198,8 +197,7 @@
         "extra":
           {  } },
       { "name": "getDownloadUrl",
-        "labels":
-          [ "changed" ],
+        "labels": [],
         "nameParams": [],
         "params":
           [ { "name": "fileUrl",
@@ -725,7 +723,9 @@
                 " to be used even after the Promise is resolved. Before they can be used, they",
                 " must first undergo transcoding. The [`onFileUploaded()`](wix-media-backend.Events.html#onFileUploaded)",
                 " event is triggered when an imported file has been uploaded and before the transcoding is finished. As a result, some properties",
-                " such as the `fileUrl` may not initially appear in the returns." ],
+                " such as the `fileUrl` may not initially appear in the returns.   ",
+                "",
+                " >**Note:** Receiving a response does not indicate that the import is complete. To run code when the import finishes, implement the relevant [event](/wix-media-backend/events/introduction). See [Importing and Uploading Files](https://dev.wix.com/docs/velo/api-reference/wix-media-backend/importing-and-uploading-files) to learn more." ],
             "links": [],
             "examples":
               [ { "title": "Import a file",
@@ -1197,8 +1197,7 @@
         "extra":
           {  } },
       { "name": "moveFilesToTrash",
-        "labels":
-          [ "changed" ],
+        "labels": [],
         "nameParams": [],
         "params":
           [ { "name": "fileUrls",
@@ -1420,7 +1419,9 @@
                 " ",
                 " To enable site visitors to upload files to your site, you can also use an [upload button](https://www.wix.com/velo/reference/$w/uploadbutton).",
                 "",
-                " >**Note:** There are limits on the size and duration of files that you can upload. See [Wix Media: Supported Media File Types and File Sizes](https://support.wix.com/en/article/wix-media-supported-media-file-types-and-file-sizes) for more details." ],
+                " >**Notes:** ",
+                " > - There are limits on the size and duration of files that you can upload. See [Wix Media: Supported Media File Types and File Sizes](https://support.wix.com/en/article/wix-media-supported-media-file-types-and-file-sizes) for more details.",
+                " > - Receiving a response does not indicate that the import is complete. To run code when the upload finishes, implement the relevant [event](/wix-media-backend/events/introduction). See [Importing and Uploading Files](https://dev.wix.com/docs/velo/api-reference/wix-media-backend/importing-and-uploading-files) to learn more." ],
             "links": [],
             "examples":
               [ { "title": "Upload a file",
@@ -2177,15 +2178,16 @@
               "optional": true },
             { "name": "context",
               "type": "Object",
-              "doc": "An object of key:value string pairs that is sent\n back in the [`onFileUploaded()`](wix-media-backend.Events.html#onFileUploaded)\n event.",
+              "doc": "An object of key:value string pairs containing information that is passed to the [`onFileUploaded()`](/wix-media-backend/events/on-file-uploaded), [`onAudioTranscoded()`](/wix-media-backend/events/on-audio-transcoded), or [`onVideoTranscoded()`](/wix-media-backend/events/on-video-transcoded) events. See [Importing and Uploading Files](https://dev.wix.com/docs/velo/api-reference/wix-media-backend/importing-and-uploading-files) to learn more.\n back in the [`onFileUploaded()`](wix-media-backend.Events.html#onFileUploaded)\n event.",
               "optional": true },
             { "name": "fileName",
               "type": "string",
               "doc": "In this case the fileName is the name you would like your file to appear as in the Media Manager.",
               "optional": true } ],
         "extra":
           {  },
-        "labels": [] },
+        "labels":
+          [ "changed" ] },
       { "name": "PaginationOptions",
         "locations":
           [ { "lineno": 47,

wix-media-manager-backend/wix-media-backend/guides/Importing and Uploading Files.md

@@ -0,0 +1,36 @@
+# Importing and Uploading Files
+
+When you [import](/wix-media-backend/media-manager/import-file) or [upload](/wix-media-backend/media-manager/upload) a file, it's not immediately available, meaning you can't manage or use the file straight away. Files can take time to import or upload and be processed. This is true even though the function used to import or upload a file returns a successful response.
+
+To run code when a file finishes processing successfully, use the [`onFileUploaded()`](wix-media-backend/events/on-file-uploaded) event. For audio or video files, use [`onAudioTranscoded()`](/wix-media-backend/events/on-audio-transcoded) or [`onVideoTranscoded()`](/wix-media-backend/events/on-video-transcoded).
+
+## Using `context`
+
+The [`import()`](/wix-media-backend/media-manager/import-file), [`upload()`](/wix-media-backend/media-manager/upload), and [`getUploadUrl()`](/wix-media-backend/media-manager/get-upload-url) functions have a parameter called `context`. 
+Arguments passed to this parameter are included only in the `wix-media-backend` event bodies. 
+
+Use `context` to pass information to the events that isn't contained in the file descriptor object.
+
+### `context` use case
+
+Here is a sample flow to show how you could use `context` effectively.
+
+There is a form on a site that sends site visitors a confirmation email with the details they submitted in the form. One of the form fields is an image URL.
+In the email, we want to send a Wix download URL for the image, not the original image URL. This means we can only send the email when the image file is ready to download.
+
+To implement this, we use the following flow:
+1. When the user submits the form, send the form information to a [data collection](/wix-data/introductionn), getting back the form data's `_id`.
+1. Use [`import()`](/wix-media-backend/media-manager/import-file) to upload the image to the Media Manager. Include the `context` parameter as follows:
+    ```json
+    {
+      "context": {
+        "origin": "formBuilder",
+        "externalIds": ["_id"]
+      }
+    }
+    ```
+1. Add the [`onFileUploaded()`](wix-media-backend/events/on-file-uploaded) event in your **events.js** file, and implement the following steps to handle the event:
+    1. Check that the value for `context.origin` is `formBuilder`. We don't want to run this code if media was added from a different source.
+    1. Use the `_id` to [retrieve the form details](data-items/save-data-item) from the CMS.
+    1. [Get a download URL](/wix-media-backend/media-manager/get-download-url) for the image.
+    1. Send the confirmation email with the form details and the download URL.