Merge pull request #230977 from sarkar-rajarshi/rsarkar/call-recording-byos

Call Recording BYOS private preview docs initial commit

Author: ttorble

articles/communication-services/concepts/voice-video-calling/call-recording.md

@@ -22,12 +22,13 @@ ms.subservice: calling
 Call Recording enables you to record multiple calling scenarios available in Azure Communication Services by providing you with a set of APIs to start, stop, pause and resume recording. Whether it's a PSTN, WebRTC, or SIP call, these APIs can be accessed from your server-side business logic. Also, recordings can be triggered by a user action that tells the server application to start recording. 
 
 Depending on your business needs, you can use Call Recording for different Azure Communication Services calling implementations.
-For example, you can record 1:1 or 1:N scenarios for audio and video calls enabled by [Calling Client SDK](https://learn.microsoft.com/azure/communication-services/concepts/voice-video-calling/calling-sdk-features). 
+For example, you can record 1:1 or 1:N scenarios for audio and video calls enabled by [Calling Client SDK](./calling-sdk-features.md). 
 
 ![Diagram showing a call that it's being recorded.](../media/call-recording-client.png)
 
-But also, you can use Call Recording to record complex PSTN or VoIP inbound and outbound calling workflows managed by [Call Automation](https://learn.microsoft.com/azure/communication-services/concepts/voice-video-calling/call-automation).
-Regardless of how you establish the call, Call Recording allows you to produce mixed or unmixed media files that are stored for 48 hours on a built-in temporary storage. You can retrieve the files and take them to the long-term storage solution of your choice. Call Recording supports all Azure Communication Services data regions.
+But also, you can use Call Recording to record complex PSTN or VoIP inbound and outbound calling workflows managed by [Call Automation](../call-automation/call-automation.md).
+Regardless of how you established the call, Call Recording allows you to produce mixed or unmixed media files that are stored for 48 hours on a built-in temporary storage. You can retrieve the files and take them to the long-term storage solution of your choice. Call Recording supports all Azure Communication Services data regions.
+
 
 ![Diagram showing call recording architecture using calling client sdk.](../media/call-recording-with-call-automation.png)
 
@@ -64,7 +65,9 @@ A `recordingId` is returned when recording is started, which is then used for fo
 
 
 ## Event Grid notifications
-Call Recording uses [Azure Event Grid](https://learn.microsoft.com/azure/event-grid/event-schema-communication-services) to provide you with notifications related to media and metadata.
+
+Call Recording use [Azure Event Grid](../../../event-grid/event-schema-communication-services.md) to provide you with notifications related to media and metadata.
+
 
 > [!NOTE]
 > Azure Communication Services provides short term media storage for recordings. **Recordings will be available to download for 48 hours.** After 48 hours, recordings will no longer be available.
@@ -143,11 +146,11 @@ Regulations around the maintenance of personal data require the ability to expor
 
 ## Known Issues
 
-It's possible that when a call is created using Call Automation, you don't get a value in the `serverCallId`. If that's the case, get the `serverCallId` from the `CallConnected` event method described in [Get serverCallId](https://learn.microsoft.com/azure/communication-services/quickstarts/voice-video-calling/callflows-for-customer-interactions?pivots=programming-language-csharp#configure-programcs-to-answer-the-call).
+It's possible that when a call is created using Call Automation, you won't get a value in the `serverCallId`. If that's the case, get the `serverCallId` from the `CallConnected` event method described in [Get serverCallId](../../quickstarts/call-automation/callflows-for-customer-interactions.md).
 
 ## Next steps
 For more information, see the following articles:
 
 - Learn more about Call recording, check out the [Call Recording Quickstart](../../quickstarts/voice-video-calling/get-started-call-recording.md).
-- Learn more about [Call Automation](https://learn.microsoft.com/azure/communication-services/quickstarts/voice-video-calling/callflows-for-customer-interactions?pivots=programming-language-csharp).
-- Learn more about [Video Calling](https://learn.microsoft.com/azure/communication-services/quickstarts/voice-video-calling/get-started-with-video-calling?pivots=platform-web).
+- Learn more about [Call Automation](../../quickstarts/call-automation/callflows-for-customer-interactions.md).
+- Learn more about [Video Calling](../../quickstarts/voice-video-calling/get-started-with-video-calling.md).

articles/communication-services/quickstarts/voice-video-calling/get-started-call-recording.md

@@ -16,7 +16,7 @@ ms.custom: mode-api
 
 [!INCLUDE [Public Preview](../../includes/public-preview-include-document.md)]
 
-This quickstart gets you started with Call Recording for voice and video calls. To start using the Call Recording APIs, you must have a call in place. Make sure you're familiar with [Calling client SDK](get-started-with-video-calling.md) and/or [Call Automation](https://learn.microsoft.com/azure/communication-services/quickstarts/voice-video-calling/callflows-for-customer-interactions?pivots=programming-language-csharp#configure-programcs-to-answer-the-call) to build the end-user calling experience. 
+This quickstart gets you started with Call Recording for voice and video calls. To start using the Call Recording APIs, you must have a call in place. Make sure you're familiar with [Calling client SDK](get-started-with-video-calling.md) and/or [Call Automation](../call-automation/callflows-for-customer-interactions.md#build-a-customer-interaction-workflow-using-call-automation) to build the end-user calling experience. 
 
 ::: zone pivot="programming-language-csharp"
 [!INCLUDE [Test Call Recording with C#](./includes/call-recording-samples/call-recording-csharp.md)]
@@ -26,6 +26,7 @@ This quickstart gets you started with Call Recording for voice and video calls.
 [!INCLUDE [Test Call Recording with Java](./includes/call-recording-samples/call-recording-java.md)]
 ::: zone-end
 
+
 ## Clean up resources
 
 If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. Learn more about [cleaning up resources](../create-communication-resource.md#clean-up-resources).
@@ -36,5 +37,5 @@ For more information, see the following articles:
 
 - Download our [Java](https://github.com/Azure-Samples/communication-services-java-quickstarts/tree/main/ServerRecording) and [.NET](https://github.com/Azure-Samples/communication-services-dotnet-quickstarts/tree/main/ServerRecording) call recording sample apps 
 - Learn more about [Call Recording](../../concepts/voice-video-calling/call-recording.md)
-- Learn more about [Call Automation](https://learn.microsoft.com/azure/communication-services/concepts/voice-video-calling/call-automation)
+- Learn more about [Call Automation](../../concepts/call-automation/call-automation.md)
 

articles/communication-services/quickstarts/voice-video-calling/includes/call-recording-samples/private-preview-call-recording-byos-csharp.md

@@ -0,0 +1,66 @@
+---
+author: rsarkar
+ms.service: azure-communication-services
+ms.date: 03/15/2023
+ms.topic: include
+ms.custom: private_preview
+ms.author: rsarkar
+---
+
+[!INCLUDE [Private Preview](../../../../includes/private-preview-include-section.md)]
+
+
+## Start recording session with external storage specified
+
+Use the server call ID received during initiation of the call.
+
+### Using Azure Blob Storage for External Storage
+
+
+```csharp
+StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<ServerCallId>"))
+{
+    // ...
+    ExternalStorage = new BlobStorage(new Uri("<Insert Container / Blob Uri>"))
+};
+
+Response<RecordingStateResult> startRecordingWithResponse = await callAutomationClient.GetCallRecording()
+        .StartRecordingAsync(options: recordingOptions);
+```
+
+##	Notification on successful export
+
+Use an [Azure Event Grid](../../../../../event-grid/overview.md) web hook or other triggered action should be used to notify your services when the recorded media is ready and have been exported to the external storage location.
+
+Below is an example of the event schema.
+
+``` json
+{
+    "id": "string", // Unique guid for event
+    "topic": "string", // /subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}
+    "subject": "string", // /recording/call/{call-id}/serverCallId/{serverCallId}
+    "data": {
+        "storageType": "string", // acsstorage, blobstorage etc.
+        "recordingId": "string", // unique id for recording
+        "recordingStorageInfo": {
+            "recordingChunks": [
+                {
+                    "documentId": "string", // Document id for for the recording chunk
+                    "contentLocation": "string", //Azure Communication Services URL where the content is located
+                    "metadataLocation": "string", // Azure Communication Services URL where the metadata for this chunk is located
+                    "deleteLocation": "string", // Azure Communication Services URL to use to delete all content, including recording and metadata.
+                    "index": "int", // Index providing ordering for this chunk in the entire recording
+                    "endReason": "string", // Reason for chunk ending: "SessionEnded", "ChunkMaximumSizeExceeded”, etc.
+                }
+            ]
+        },
+        "recordingStartTime": "string", // ISO 8601 date time for the start of the recording
+        "recordingDurationMs": "int", // Duration of recording in milliseconds
+        "sessionEndReason": "string" // Reason for call ending: "CallEnded", "InitiatorLeft”, etc.
+    },
+    "eventType": "string", // "Microsoft.Communication.RecordingFileStatusUpdated"
+    "dataVersion": "string", // "1.0"
+    "metadataVersion": "string", // "1"
+    "eventTime": "string" // ISO 8601 date time for when the event was created
+}
+```

articles/communication-services/quickstarts/voice-video-calling/includes/call-recording-samples/private-preview-call-recording-byos-java.md

@@ -0,0 +1,62 @@
+---
+author: rsarkar
+ms.service: azure-communication-services
+ms.date: 03/15/2023
+ms.topic: include
+ms.custom: private_preview
+ms.author: rsarkar
+---
+
+[!INCLUDE [Private Preview](../../../../includes/private-preview-include-section.md)]
+
+## Start recording session with external storage specified
+
+Use the server call ID received during initiation of the call.
+
+### Using Azure Blob Storage for External Storage
+
+
+```java
+StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<serverCallId>"))
+                .setExternalStorage(new BlobStorage("<Insert Container / Blob Uri>"));
+
+Response<StartCallRecordingResult> response = callAutomationClient.getCallRecording()
+.startRecordingWithResponse(recordingOptions, null);
+```
+
+## Notification on successful export
+
+Use an [Azure Event Grid](../../../../../event-grid/overview.md) web hook or other triggered action should be used to notify your services when the recorded media is ready and have been exported to the external storage location.
+
+Below is an example of the event schema.
+
+``` json
+{
+    "id": "string", // Unique guid for event
+    "topic": "string", // /subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}
+    "subject": "string", // /recording/call/{call-id}/serverCallId/{serverCallId}
+    "data": {
+        "storageType": "string", // acsstorage, blobstorage etc.
+        "recordingId": "string", // unique id for recording
+        "recordingStorageInfo": {
+            "recordingChunks": [
+                {
+                    "documentId": "string", // Document id for for the recording chunk
+                    "contentLocation": "string", //Azure Communication Services URL where the content is located
+                    "metadataLocation": "string", // Azure Communication Services URL where the metadata for this chunk is located
+                    "deleteLocation": "string", // Azure Communication Services URL to use to delete all content, including recording and metadata.
+                    "index": "int", // Index providing ordering for this chunk in the entire recording
+                    "endReason": "string", // Reason for chunk ending: "SessionEnded", "ChunkMaximumSizeExceeded”, etc.
+                }
+            ]
+        },
+        "recordingStartTime": "string", // ISO 8601 date time for the start of the recording
+        "recordingDurationMs": "int", // Duration of recording in milliseconds
+        "sessionEndReason": "string" // Reason for call ending: "CallEnded", "InitiatorLeft”, etc.
+    },
+    "eventType": "string", // "Microsoft.Communication.RecordingFileStatusUpdated"
+    "dataVersion": "string", // "1.0"
+    "metadataVersion": "string", // "1"
+    "eventTime": "string" // ISO 8601 date time for when the event was created
+}
+```