Cisco MediaSense Developer Guide, Release 10.5(1)
Bias-Free Language
The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
- Updated:
- June 29, 2015
Chapter: List of APIs
List of APIs
User Authentication
Use these APIs to authenticate a user. A user must be signed in before they can use any other API. This signIn API returns a JSESSIONID that must be used in all subsequent requests to authenticate. If the requests are made from a browser, then the browser automatically handles the session for the clients.
The JSESSIONID expires when the user logs out or after 30 minutes of inactivity, whichever comes first.
signIn
| Description: | Use this API for user authentication/sign-in. If the signIn is successful, a JSESSIONID is returned as a cookie in the header of the HTTP response. This JSESSIONID serves as a token of authentication and must be passed in all subsequent requests. The JSESSIONID expires when the user signs out or after 30 minutes of inactivity, whichever comes first. |
| API URI: | https://<host>:<port>/ora/authenticationService/authentication/signIn |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters": {
"username": "<replace with your string>",
"password": "<replace with your string>"
},
"authenticationProviders": ["<replace with your string>",
"<replace with your string>",...]
}
|
| Header parameters: | None |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful"
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: | None |
| Availability: |
Available since API Version 1.0. Modified in API Version 1.5 (See Notes below.) |
| Release: | 8.5(1) |
| Notes: |
When an API user's password changes in Unified Communications Manager, it may take several minutes for that change to be reflected in MediaSense. A successful response also returns a JSESSIONID inside a cookie. This JSESSIONID is a session identifier and serves as a means of authentication for the subsequent requests. The following change was introduced in Release 10.0, Version 1.5:
|
| Examples: |
Example 1 To signIn a user with username " myUser " and password " cisco " on the server 10.194.118.1 at port 8440 : Since no authentication provider has been specified, this request will try to authenticate against all possible configured authentication providers including AXL & Finesse. HTTPS POST: https://10.194.118.1:8440/ora/authenticationService/ authentication/signIn Headers: Content-Type: application/json Body:
{
"requestParameters": {
"username":"myUser",
"password":"cisco"
}
}
|
|
Example 2 To signIn a Finesse supervisor with username " myUser " and password " cisco " on the server 10.194.118.1 at port 8440: HTTPS POST: https://10.194.118.1:8440/ora/authenticationService/ authentication/signIn Headers: Content-Type: application/json Body:
{
"requestParameters": {
"username":"myUser",
"password":"cisco"
},
"authenticationProviders": ["FINESSE"]
}
|
signOut
| Description: | This API is used to sign out the user. The user requires no parameter other than JSESSIONID to sign out. |
| API URI: | https://<host>:<port>/ora/authenticationService/authentication/signOut |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: | None |
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful"
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
)
|
| Related error codes: |
See API Response Codes. |
| Events triggered: | None |
| Availability: | Available since API Version 1.0. |
| Release: | 8.5(1) |
| Example: |
To signOut a user who was previously signed in: HTTPS POST: https://10.194.118.1:8440/ora/authenticationService/ authentication/signOut Headers: JSESSIONID: <the jsessionId received from a previous signIn request> Content-Type: application/json The user identified by the JSESSIONID is signed out. |
Event Subscription
subscribeToEvents
| Description: | Use this API to receive event notifications, such as when recording starts, recording ends, recording data gets updated, a tag is added to the recording, or when a tag is deleted from the recording. You may choose to subscribe to all events, categories of events or specific types of events. |
| API URI: | https://<host>:<port>/ora/eventService/event/subscribeToEvents |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
If this subscription is for server-based clients, set the
client's subscriptionType parameter to "http" (where it
should receive events).
{
"requestParameters": {
"subscriptionType" : "<replace with
your string>",
"subscriptionUri" : "<replace with
your string>",
"subscriptionFilters": ["<replace with
your string>", "<replace with your
string>",...],
"tagNameRegEx": "<java-regular-
expression>"
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"responseBody" : {
"subscriptionId": "<This is a String>",
"subscriptionFilters": ["<This is a
String>", "<This is a String>",...],
"tagNameRegEx": "<java-regular-expression>"
}
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: |
Event type: storageThresholdEvent Event action: event action values |
| Availability: |
Available since API Version 1.1 Modified in API Version 1.2 See the following notes. |
| Release: | 8.5(2) |
| Notes: |
If the same subscriptionUri is subscribed for a second time, the subscriptionFilters in the existing subscription will be replaced with the new subscriptionFilters. If the subscriptionFilters are also the same, then no error is generated. A 2005 responseCode is generated indicating that the subscription already exists. The following changes were introduced in Release 8.5(3), Version 1.2 |
| Examples: |
Example 1: To receive event notifications for all events: HTTPS POST: https://10.194.118.1:8440/ora/eventService/event/ subscribeToEvents Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{
requestParameters: {
"subscriptionType": "http",
"subscriptionUri": "http://10.35.146.157:
8085/sessionEvent",
"subscriptionFilters": ["ALL_EVENTS"]
}
}
Response:
{
"responseMessage": "Success: Your request was successfully
completed.",
"responseCode": 2000,
"responseBody": {
"subscriptionFilters": [
"EXIT_EMERGENCY_STORAGE_SPACE_EVENT",
"TAG_ADDED_EVENT",
"TAG_DELETED_EVENT",
"TAG_UPDATED_EVENT",
"SESSION_STARTED_EVENT",
"SESSION_ENDED_EVENT",
"EXIT_LOW_STORAGE_SPACE_EVENT",
"EXIT_CRTITICAL_STORAGE_SPACE_EVENT",
"ENTER_CRTITICAL_STORAGE_SPACE_EVENT",
"ENTER_LOW_STORAGE_SPACE_EVENT",
"SESSION_UPDATED_EVENT",
"SESSION_DELETED_EVENT",
"ENTER_EMERGENCY_STORAGE_SPACE_EVENT",
"SESSION_PRUNED_EVENT"
],
"subscriptionId": "3oV6jCEnJUlGYZo8"
}
}
|
|
Example 2 To receive event notifications for onlyTAG_EVENTS : HTTPS POST: https://10.194.118.1:8440/ora/eventService/event/ subscribeToEvents Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{
requestParameters: {
"subscriptionType": "http",
"subscriptionUri": "http://10.35.146.157:
8085/sessionEvent",
"subscriptionFilters": ["TAG_EVENTS"]
}
}
Response:
{
"responseMessage": "Success: Your request was successfully
completed.",
"responseCode": 2000,
"responseBody": {
"subscriptionFilters": [
"TAG_ADDED_EVENT",
"TAG_DELETED_EVENT",
"TAG_UPDATED_EVENT"
],
"subscriptionId": "D52C4aeXISTURzM7"
}
}
|
unsubscribeFromEvents
| Description: | Use this API to stop receiving recording events:
|
| API URI: | https://<host>:<port>/ora/eventService/event/unsubscribeFromEvents |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters": {
"subscriptionId" : "<replace with
your string>",
"subscriptionFilters": ["<replace with
your string>", "<replace with your
string>",...]
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful"
}
{
"responseCode": 2006,
"responseMessage": "Success: The current subscription has been
updated and you have been unsubscribed
from the subscriptionFilters requested.
The subscription is still active.",
"responseBody": {
"subscriptionFilters": ["<This is a String>",
"<This is a String>",...]
},
"tagNameRegEx": "<java-regular-expression>"
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: | None |
| Availability: |
Available since API Version 1.1 Modified in API Version 1.2 See the following notes. |
| Release: | 8.5(2) |
| Notes: |
The following changes were introduced in Release 8.5(3), Version 1.2: |
| Examples: |
Example 1 To stop receiving event notifications for any event (unsubscribe from all events): HTTPS POST: https://10.194.118.1:8440/ora/eventService/event/ unsubscribeFromEvents Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{
requestParameters: {
"subscriptionId": "sN7DASoAArHmDfI1",
"subscriptionFilters":[ALL_EVENTS]
}
}
OR
{
requestParameters: {
"subscriptionId": "sN7DASoAArHmDfI1"
}
}
Response:
{
"responseCode": 2000,
"responseMessage": "Successful"
}
|
|
Example 2 The client is currently subscribed to RECORDING_EVENTS and CLEANUP_EVENTS and now wants to unsubscribe from CLEANUP_EVENTS, but continue to maintain their subscription to RECORDING_EVENTS. HTTPS POST: https://10.194.118.1:8440/ora/eventService/event/ unsubscribeFromEvents Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{
requestParameters: {
"subscriptionId": "sN7DASoAArHmDfI1",
"subscriptionFilters":[CLEANUP_EVENTS]
}
}
Response: (This will tell the client the filters they are still subscribed to.)
{
"responseMessage": "Success: Your request was successfully
completed.",
"responseCode": 2000,
"responseBody": {
"subscriptionFilters": [
"SESSION_STARTED_EVENT",
"SESSION_UPDATED_EVENT",
"SESSION_ENDED_EVENT"
]
}
}
|
verifyEventSubscription
| Description: | Use this API to verify if the subscription to receive events is active or not. |
| API URI: | https://<host>:<port>/ora/eventService/event/verifyEventSubscription |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters": {
"subscriptionId": "<this is a string>"
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"responseBody": {
"subscriptionStatus":"<this is a String>",
"subscriptionFilters": ["<this is a String>",
"<this is a String>",...],
"tagNameRegEx": "<java-regular-expression>"
}
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: | None |
| Availability: |
Available since API Version 1.1 Modified in API Version 1.2 See the following notes. |
| Release: | 8.5(2) |
| Notes: |
The subscriptionStatus will be ACTIVE or INACTIVE depending upon whether the subscription exists or not. MediaSense does not store subscriptions in terms of event categories. Categories are always expanded into a corresponding list of eventTypes and stored as such. Therefore the list of Strings included in subscriptionFilters is always a list of eventTypes, and never contains any category names. The following changes were introduced in Release 8.5(3), Version 1.2: |
| Examples: |
Example 1 Assuming that you are currently subscribed to receive all RECORDING_EVENTS, use the following API to verify that your subscription to is active: HTTPS POST: https://10.194.118.1:8440/ora/eventService/event/ verifyEventSubscription Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{
requestParameters: {
"subscriptionId": "sN7DASoAArHmDfI1"
}
}
Response:
{
"responseMessage": "Success: Your request was successfully
completed.",
"responseCode": 2000,
"responseBody": {
"subscriptionFilters": [
"SESSION_STARTED_EVENT",
"SESSION_UPDATED_EVENT",
"SESSION_ENDED_EVENT"
],
"subscriptionStatus": "ACTIVE"
}
}
|
|
Example 2 Verify an INACTIVE subscription. HTTPS POST: https://10.194.118.1:8440/ora/eventService/event/ verifyEventSubscription Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{
requestParameters: {
"subscriptionId": "sN7DASoAArHmDfI2"
}
}
Response:
{
"responseMessage": "Success: Your request was successfully
completed.",
"responseCode": 2000,
"responseBody": {
"subscriptionStatus": "INACTIVE"
}
}
|
subscribeRecordingEvent (deprecated)
| Description: | Use this API to receive event notifications, such as when recording starts, recording ends, recording data gets updated, a tag is added to the recording, or when a tag is deleted from the recording. |
| API URI: | https://<host>:<port>/ora/eventService/event/subscribeRecordingEvent |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
If this subscription is for server-based clients, set the
client's subscriptionType parameter to "http" (where it
should receive events).
{
"requestParameters": {
"subscriptionType" : "<this is a
string>",
"subscriptionUri" : "<this is a
string>"
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"subscriptionId": "abcd1234",
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>",
"subscriptionId": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: |
Event type: storageThresholdEvent Event action: event action values |
| Availability: | Available since API Version 1.0.
Deprecated in API Version 1.1, instead use subscribeToEvents. |
| Release: | 8.5(1) |
| Notes: | If the same subscriptionUri is subscribed for a second time, an error will be returned and it will contain the original subscriptionId. |
unsubscribeRecordingEvent (deprecated)
| Description: | Use this API to stop receiving recording events. |
| API URI: | https://<host>:<port>/ora/eventService/event/unsubscribeRecordingEvent |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters": {
"subscriptionId" : "<this is a string>"
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter Description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful"
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: | None |
| Availability: | Available since API Version 1.0
Deprecated in API Version 1.1 , instead use subscribeToEvents. |
| Release: | 8.5(1) |
| Notes: | None |
verifyRecordingSubscription (deprecated)
| Description: | Use this API to verify if the recording subscription is active. |
| API URI: | https://<host>:<port>/ora/eventService/event/verifyRecordingSubscription |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters": {
"subscriptionId": "<this is a string>"
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"subscriptionStatus":"ACTIVE"
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: | None |
| Availability: | Available since API Version 1.0
Deprecated in API Version 1.1, instead use verifyEventSubscription. |
| Release: | 8.5(1) |
| Notes: | The subscriptionStatus is active or inactive depending upon whether the subscription exists or not. |
Job Management
Use these APIs to create or cancel jobs. A job can contain one or more operations and takes a significant amount of time to complete. Each result is provided on a per-operation basis. The purpose of a job is to allow the system to accept and act on the job request without requiring a persistent client connection to the server until the job is completed.
The job may not eventually be acted upon, as it might be disallowed during the processing phase. There is no response mechanism to return an unfinished job. Use the Job Query API to retrieve the job status and operation results.
cancelJob
| Description: | Use this API to cancel a job that is already in progress. This API only stops the execution of a job. To delete the job from the database, use the deleteJob API. |
| API URI: | https://<host>:<port>/ora/managementService/manage/cancelJob |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters": {
"jobId": "<replace with your string>"
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"jobId": "<this is a string>"
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>",
"jobId": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: | None |
| Availability: | Available since API Version 1.0 |
| Release: | 8.5(1) |
| Notes: |
This API cancels a job which is in progress. If the job is not in a RUNNING state, then it returns a failure error code along with the current job state. |
| Example: |
HTTPS POST: https://10.194.118.1:8440/ora/managementService/manage/cancelJob Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{
"requestParameters": {
"jobId": "123456789"
}
}
Response:
{
"responseMessage": "Success: Your request was successfully completed.",
"responseCode": 2000,
"jobId": "123456789"
}
|
createJob
| Description: | Use this API to create a batch process for jobs which take a significant amount of time to complete. The results are provided for each operation. |
| API URI: | https://<host>:<port>/ora/managementService/manage/createJob |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters": {
"jobType": "<replace with your string>",
"jobParameters": "<replace with your string>"
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"jobId": "<this is a string>"
}
|
| Failure JSON response schema: |
|
| Related error codes: |
See API Response Codes. |
| Events triggered: | None |
| Availability: | Available since API Version 1.0 |
| Release: | 8.5(1) |
| Notes: |
See Job States. |
deleteJob
| Description: | Use this API to delete a job from the database. This API is only applicable to a job that is already completed, canceled, or in an error state. If the job is in the RUNNING state, use the cancelJob API to first stop the job, and then use the deleteJob API to delete that job. This API deletes job details and all job results from the database. |
| API URI: | https://<host>:<port>/ora/managementService/manage/deleteJob |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters": {
"jobId": "<replace with your string>"
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"jobId": "<this is a string>"
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>",
"jobId": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: | None |
| Availability: | Available since API Version 1.0 |
| Release: | 8.5(1) |
| Example: |
HTTPS POST: https://10.194.118.1:8440/ora/managementService/manage/deleteJob Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{
"requestParameters": { "jobId": "JobId_1" }
}
Response:
{ "responseMessage": "Success: Your request was successfully
completed.", "responseCode": 2000, "jobId": "JobId_1" }
|
Job Query
Use these APIs to retrieve the status and results for jobs created using the job management APIs.
getJobById
| Description: | Use this API to retrieve existing jobs using the jobId. In successful JSON response fields, the jobstate, operationsCompleted, and operationsRemaining parameter values are retrieved at the time the API is called. Subsequent calls to this API may display different values. |
| API URI: | https://<host>:<port>/ora/queryService/query/getJobById |
| Supported response formats: | JSON |
| HTTP method: | GET |
| Request parameters: |
{ "jobId": "<replace with your string>" }
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000
"responseMessage": "Successful"”
"responseBody": {
"jobs":[{
"jobType":"<this is a string>",
"jobDuration":<this is an integer>,
"jobStartTime":<this is an integer>,
"jobId":"<this is a string>",
"jobState":"<this is a string>",
"operationsCompleted":<this is an integer>,
"operationsRemaining":<this is an integer>
}]
}
}
|
| Failure JSON response schema: |
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>",
"jobId": "<this is a string>"}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: | None |
| Availability: | Available since API Version 1.0 |
| Release: | 8.5(1) |
| Notes: |
See Job States. |
| Example: |
HTTPS GET: https://10.194.118.1:8440/ora/queryService/query/ getJobById?jobId=AMS_10.194.118.1_1282948026491_5 Headers: JSESSIONID: <the jsessionId received from a previous signIn request> Response:
{
"responseMessage": "Success: Your request was
successfully completed.",
"responseCode": 2000,
"responseBody": {
"jobs": [
{
"jobType": "BULK_DELETE_SESSIONS",
"jobDuration": 203567,
"jobStartTime": 1343333766345,
"jobId": "AMS_10.194.118.1_
1282948026491_5",
"jobState": "COMPLETED"
}
],
"operationsCompleted": 2,
"operationsRemaining": 0
}
}
|
getJobResult
| Description: | Use this API to retrieve job results of existing jobs. The "requestParameters" parameter is optional. If it is not specified, all job operations for the specified job id will be returned. If the query filter specified in the "requestParameters" parameter does not match any job operation for the specified job id, then the response will not contain the "jobOperationResultset" parameter. |
| API URI: | https://<host>:<port>/ora/queryService/query/getJobResult |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"jobId": "<replace with your string>",
"requestParameters": [
{
"fieldName" : "<replace with your string>",
"fieldConditions": [
{
"fieldOperator" : "<replace with
your string>",
"fieldValues": [
"<replace with your string>",
"<replace with your string>",
…
],
"fieldConnector": "<replace with
your string>" }
],
"paramConnector": "<replace with your
string>" }
],
"pageParameters": {
"offset": <replace with your integer>,
"limit": <replace with your integer> },
"sortParameters": [
{
"byFieldName": "<replace with your string>",
"order": "<replace with your string>" }
]
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "<this is a string>",
"responseBody": {
"job": [
{
"jobType":"<this is a string>",
"jobDuration":<this is an integer>,
"jobStartTime": "<this is a string>",
"jobId": "<this is a string>",
"jobState": "<this is a string>"
}
] ,
"jobOperationsResultset": [
{
"responseCode": <this is an integer>,
"operationData": "<this is a string>",
"operationId": "<this is a string>",
"operationResponse": "<this is a
string>" },
{
.. ..
},
..
]
}
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>",
"jobId": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: | None |
| Availability: | Available since API Version 1.0 |
| Release: | 8.5(1) |
| Notes: |
See Job States. |
| Example: |
HTTPS POST: https://10.194.118.1:8440/ora/queryService/query/ getJobResult Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> |
|
Body:
{
"jobId": "AMS_10.27.185.20_1287093966514_162",
"requestParameters": [
{
"fieldName" : "operationResult",
"fieldConditions": [
{
"fieldOperator" : "equals",
"fieldValues" : [
"2000"
]
}
]
}
],
"sortParameters": [
{
"byFieldName": "operationResult",
"order": "ASC"
}
]
}
|
|
|
Response:
{
"responseMessage": "Success: Your request was
successfully completed.",
"responseCode": 2000,
"responseBody": {
"job": {
"jobType": "BULK_DELETE_SESSIONS",
"jobDuration": 36005,
"jobId": "AMS_10.27.185.20_1287093966514_
162",
"jobStartTime": 1287171904409,
"jobState": "COMPLETED"
},
"jobOperationsResultset": [
{
"responseCode": 2000,
"operationData": "Session-1-10.194.118.
92-1287017042781",
"jobOperationId": "AMS_10.27.185.20_
1287093966514_163",
"OperationResponse": "Successful: Your
request was successfully completed."
},
{
"responseCode": 2000,
"operationData": "Session-11-10.194.118.
92-1287178816956",
"jobOperationId": "AMS_10.27.185.20_
1287093966514_164",
"OperationResponse": "Successful: Your
request was successfully completed."
}
]
}
}
|
Parameter Details for getJobResult
fieldOperators for getJobResult
| Parameter | Allowed fieldOperators for this parameter |
|---|---|
| operationId | equals |
| operationData | equals |
| operationResult | equals |
| operationFailureReason |
equals contains startsWith endsWith |
Enumerations for getJobResult
| Parameter | Allowed enumerations for this parameter |
|---|---|
| byFieldName |
operationId operationData operationResponse |
getJobs
| Description: | Use this API to retrieve existing jobs using any of the job parameter names. |
| API URI: | https://<host>:<port>/ora/queryService/query/getJobs |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters": [
{
"fieldName" : "<replace with your string>",
"fieldConditions": [
{
"fieldOperator" : "<replace with
your string>",
"fieldValues": [
"<replace with your string>",
"<replace with your string>",
…
],
"fieldConnector": "<replace with
your string>"
}
],
"paramConnector": "<replace with your
string>"
}
],
"pageParameters": {
"offset": <replace with your integer>,
"limit": <replace with your integer>" },
"sortParameters": [
{
"byFieldName": "<replace with your string>",
"order": "<replace with your string>"
}
]
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000
"responseMessage": "Successful"”
"responseBody": {
"jobs":[{
"jobType":"<this is a string>",
"jobDuration":<this is an integer>,
"jobStartTime":<this is an integer>,
"jobId":"<this is a string>",
"jobState":"<this is a string>"
}]
}
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>",
"jobId": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: | None |
| Availability: | Available since API Version 1.0 |
| Release: | 8.5(1) |
| Notes: |
See Job States. |
| Example: |
HTTPS POST: https://10.194.118.1:8440/ora/queryService/query/ getJobs Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> |
|
Body:
{
"requestParameters": [
{
"fieldName" : "jobState",
"fieldConditions": [
{
"fieldOperator" : "equals",
"fieldValues" : [
"completed"
]
}
]
}
],
"sortParameters": [
{
"byFieldName": "jobId",
"order": "ASC"
}
]
}
|
|
|
Response:
{
"responseMessage": "Success: Your request was
successfully completed.",
"responseCode": 2000,
"responseBody": {
"jobs": [
{
"jobType": "BULK_DELETE_SESSIONS",
"jobDuration": 34200,
"jobStartTime": 1343334076111,
"jobId": "Job_123",
"jobState": "COMPLETED"
},
{
"jobType": "BULK_DELETE_SESSIONS",
"jobDuration": 44200,
"jobStartTime":1343334075432,
"jobId": "Job_234",
"jobState": "COMPLETED"
},
{
"jobType": "BULK_DELETE_SESSIONS",
"jobDuration": 43678,
"jobStartTime": 1343334073567,
"jobId": "Job_345",
"jobState": "COMPLETED"
}
]
}
}
|
Parameter Details for getJobs
fieldOperators for getJobs
| Parameter | Allowed fieldOperators for this Parameter |
|---|---|
| jobId | equals |
| jobState | equals |
| jobType | equals |
| jobStartTime |
between lessThan greaterThan |
| jobDuration |
between lessThan greaterThan |
Enumerations for getJobs
| Parameter | Allowed Enumerations for this Parameter |
|---|---|
| byFieldName |
jobId jobState jobType jobStartTime jobDuration |
Recording Control
Use these APIs to perform recording control operations such as pausing and resuming a session in progress (real time).
pauseRecording
| Description: | Use this API to pause the recording of a session. |
| API URI: | https://<host>:<port>/ora/controlService/control/pauseRecording |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters": {
"sessionId": "<replace with
your string>"
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful"
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: |
Event type: tagEvent Event action: added |
| Availability: | Available since API Version 1.0 |
| Release: | 8.5(1) |
| Example: |
To pause a recording that is currently in progress: HTTPS POST: https://10.194.118.1:8440/ora/controlService/control/ pauseRecording Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{
requestParameters: {
"sessionId": "Session-1234.abc.
5678"
}
}
Response:
{
"responseCode": 2000,
"responseMessage": "Successful"
}
|
resumeRecording
| Description: | Use this API to resume recording a session. |
| API URI: | https://<host>:<port>/ora/controlService/control/resumeRecording |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters": {
"sessionId": "<replace with
your string>"
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful"
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: |
Event type: tagEvent Event action: added |
| Availability: | Available since API Version 1.0 |
| Release: | 8.5(1) |
| Example: |
HTTPS POST: https://10.194.118.1:8440/ora/controlService/control/ resumeRecording Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{
requestParameters: {
"sessionId": "Session-1234.abc.
5678"
}
}
Response:
{
"responseCode": 2000,
"responseMessage": "Successful"
}
|
startRecording
| Description: | Use this API to have MediaSense call a phone and record the recipient's audio and video input. |
| API URI: | https://<host>:<port>/ora/controlService/control/startRecording |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters": {
"deviceRef": "<replace with
your string>",
"mediaStreams":
[{
"mediaType":
"<replace with your string>"
}]
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"responseBody": {
"sessionId": "<this is a string>",
"callControllerIP": "<this is a string>",
"callControllerType": "<this is a string>",
"CCID": "<this is a string>",
"sessionStartDate": "<this is an integer>",
"sessionDuration": "<this is an integer>",
"sessionState": "<this is a string>",
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": "<this is an integer>",
"tagOffset": "<this is an integer>"
}
],
"tracks": [
{
"trackNumber": "<this is an integer>",
"trackStartDate": "<this is an integer>",
"trackDuration": "<this is an integer>",
"trackMediaType": "<this is a string>",
"downloadUrl": "<this is a string>",
"codec": "<this is a string>",
"participants": [
{
"deviceRef": "<this is a string>",
"participantStartDate": "<this
is an integer>",
"participantDuration": "<this
is an integer>",
"isConference": "<this is a
boolean>",
"deviceId": "<this is a string>"
}
]
}
],
"urls": {
"httpUrl": "<this is a string>",
"rtspUrl": "<this is a string>",
"mp4Url": "<this is a string>",
"wavUrl": "<this is a string>"
}
}
}
|
| Failure JSON response schema: |
{ "responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: |
Event type: sessionEvent Event action: started |
| Availability: |
Available since API Version 1.0. Modified in API Version 1.2 Modified in API Version 1.4 Modified in API Version 1.5 See the following notes. |
| Release: | 8.5(1) |
| Notes: |
This API requires that you configure a Call Control Service Provider in Cisco MediaSense Administration, and that the target phone be accessible by that Unified Communications Manager. |
| Examples: |
Example 1 To start a blog recording that contains both audio and video tracks on a device with deviceRef 1000: HTTPS POST: https://10.194.118.1:8440/ora/controlService/control/ startRecording Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{
"requestParameters": {
"deviceRef": "1000",
"mediaStreams": [
{
"mediaType": "VIDEO"
},
{
"mediaType": "AUDIO"
}
]
}
}
|
|
Example 2 To start a blog recording that contains only an audio track on a device with deviceRef 1111: HTTPS POST: https://10.194.118.1:8440/ora/controlService/control/ startRecording Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{
"requestParameters": {
"deviceRef": "1111",
"mediaStreams": [
{
"mediaType": "AUDIO"
}
]
}
}
|
stopRecording
| Description: | Use this API to stop device recording as soon as an outbound call (initiated by the startRecording API) is completed. |
| API URI: | https://<host>:<port>/ora/controlService/control/stopRecording |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{ "requestParameters":
{
"deviceRef": "<replace with your string>"
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"responseBody": {
"sessionId": "<this is a string>",
"callControllerIP": "<this is a string>",
"callControllerType": "<this is a string>",
"CCID": "<this is a string>",
"sessionStartDate": "<this is an integer>",
"sessionDuration": "<this is an integer>",
"sessionState": "<this is a string>",
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": "<this is an integer>",
"tagOffset": "<this is an integer>"
}
],
"tracks": [
{
"trackNumber": "<this is an integer>",
"trackStartDate": "<this is an integer>",
"trackDuration": "<this is an integer>",
"trackMediaType": "<this is a string>",
"downloadUrl": "<this is a string>",
"codec": "<this is a string>",
"participants": [
{
"deviceRef": "<this is a string>",
"participantStartDate": "<this
is an integer>",
"participantDuration": "<this
is an integer>",
"isConference": "<this is a
boolean>",
"deviceId": "<this is a string>"
}
]
}
],
"urls": {
"httpUrl": "<this is a string>",
"rtspUrl": "<this is a string>">",
"mp4Url": "<this is a string>">",
"wavUrl": "<this is a string>"
}
}
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: |
Event type: sessionEvent Event action: ended |
| Availability: |
Available since API Version 1.0. Modified in API Version 1.2 Modified in API Version 1.4 Modified in API Version 1.5 See the following notes. |
| Release: | 8.5(1) |
| Notes: | |
| Example: |
To stop a blog recording in progress on a device with deviceRef 1000: HTTPS POST: https://10.194.118.1:8440/ora/controlService/control/ stopRecording Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{ "requestParameters":
{
"deviceRef": "1000"
}
}
|
launchMediaPlayer
|
Description: |
Use this API to launch the MediaSense Media Player and play the specified recording. The API is designed to work with a server-based application that is acting as a proxy for a browser, but it can also be called directly by a browser. When an application issues this request on behalf of a browser client, it passes the JNLP file to that browser for execution. The browser then interacts with MediaSense directly to download the player application and to fetch the media stream to be played. |
||
|
API URI: |
https://<host>:<port>/ora/controlService/control/launchMediaPlayer |
||
|
Supported response formats: |
For a successful response: application/x-java-jnlp-file In case of an error : application/json |
||
|
HTTP method: |
GET |
||
|
Request parameters: |
This parameter must be specified in the query section of the URL: rtspUrl=<user provided string> Where rtspUrl is the rtsp URL of the session that is to be played in the Media Player when it launches. This URL is obtained with the Query APIs (such as getSessions). The client fetches this rtspUrl from MediaSense shortly before using it in the launchMediaPlayer request. As with all URLs provided by MediaSense, the rtspUrl for a given recorded session is subject to change from time to time without notice. |
||
|
Header parameters: |
JSESSIONID obtained from signIn API | ||
| Parameter description: |
See API Parameters. |
||
|
Successful JSON response schema: |
A JNLP file that launches the Media Player applet. |
||
|
Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
||
| Related error codes: |
See API Response Codes. |
||
| Events triggered: |
None |
||
| Availability: |
Available since API Version 1.5. |
||
| Release: | 10.0(1) | ||
| Notes: |
You must have the required version of Java installed on the client machine. See the Search & Play section of the MediaSense User Guide for more details on Java requirements. |
||
| Examples: |
Example 1 To play the session with the rtspUrl "13092154564622" in the Media Player: HTTPS GET:https://<server>:<port>/ora/controlService/control/ launchMediaPlayer?rtspUrl=rtsp://<server>/archive/2413e6746c8441 Headers: JSESSIONID (the jsessionID received from a previous signIn request) Response:
...
Content-type: application/x-java-jnlp-file
...
<?xml version="1.0" encoding="UTF-8"?>
<jnlp codebase="https://<server>:<port>/mediasense/
" spec="1.0+">
<information>
<title>MediaSensePlayer</title>
<vendor>Cisco Systems</vendor>
<homepage href="http://www.cisco.com" />
<description>MediaSensePlayer</description>
<description kind="short">MediaSensePlayer</description>
</information>
<update check="always" />
<security>
<all-permissions />
</security>
<resources>
<j2se version="1.7.0_11" />
<jar href="java/MediaSensePlayer.jar" main="true" />
<jar href="java/jna-3.4.0.jar" />
</resources>
<application-desc main-class="com.cisco.cbabu.videoplayer.
Main">
<argument>rtsp://<server>/archive/2413e6746c8441?
token=HQFmZ0yl2ynton0CvOKMifXwe6gBONLAOeMqaPzw2jTrrbhh
SjbnjOr2siZJmIIqcg2gJDNsFpMrDheQyUGYveUhDQAwdT6ze6mQeek
JPhipAhtI15Rrfaackd6r6jlj</argument>
</application-desc>
</jnlp>
Example 2 An example of a failure response. (The GET request was sent without the required rtspUrl parameter). HTTPS GET :https://<server>:<port>/ora/controlService/control/launchMediaPlayer Headers: JSESSIONID (the jsessionID received from a previous signIn request) Response:
...
Content-type: application/json
...
{
"responseMessage": "Failure: Missing parameter in message.",
"responseCode": 4061,
"detail": "rtspUrl"
}
|
Session Management
Use these APIs to manage recorded sessions. These APIs allow you to perform operations such as adding and deleting tags and deleting sessions.
addSessionTag
| Description: | Use this API to add tags to closed (already recorded) or active (currently being recorded) sessions. A tag is the name assigned by the user to label a recording. |
| API URI: | https://<host>:<port>/ora/managementService/manage/addSessionTag |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters":
{
"sessionId": "<replace with your string>",
"tagName": "<replace with
your string>",
"tagOffset": <replace with
your integer>
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful"
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: |
Event type: tagEvent Event action: added |
| Availability: | Available since API Version 1.0 |
| Release: | 8.5(1) |
| Note: |
Within Cisco, the accepted protocol when adding tags is to include a prefix and a colon (:) at the beginning of each tag to identify the application that is inserting the tag. For example, the prefix for tags inserted by CCX applications is "CCX:". Following this protocol ensures that multiple, independent client applications can insert tags into MediaSense without inadvertently inserting tag names that are meaningful or confusing to each other. |
| Example: |
HTTPS POST: https://10.10.10.10:8440/ora/managementService/manage/ addSessionTag Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{
"requestParameters":
{
"sessionId": "AMS_10.194.118.56_
1283550575777_2",
"tagName": "Sample tag",
"tagOffset": 10
}
}
Response:
{
"responseMessage":"Success: Your request was
successfully completed.",
"responseCode":2000
}
|
convertSession (Deprecated)
| Description: | Use this API to convert a MediaSense session to the format specified in the request. If your request is successful, you receive a list of links of the converted files in the response. |
| API URI: | https://<host>:<port>/ora/managementService/manage/convertSession |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters": {
"sessionId": "<replace with your
string>",
"conversionFormat": "<replace with
your string>"
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseMessage": "Success: Your request was
successfully completed.",
"responseCode": 2000,
"responseBody": {
"convertedLink": "<This is a String>"
}
}
|
| Failure JSON response schema: |
{
“responseCode”: <this is an integer>,
“responseMessage”: “Failure: <this is a string>”,
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: |
Event type: sessionEvent Event action: updated |
| Availability: |
Available since API Version 1.0 Deprecated in API Version 1.5 in favor of mp4Url. See API Parameters. |
| Release: | 8.5(1) |
| Notes: |
If the MediaSense session already exists in the request format, the existing links are returned. New links are not created in the system. If the MediaSense session is in ACTIVE or ERROR state, the session cannot be converted. Converted mp4 and wav files are deleted by the system a maximum of 2 hours after they have been created or last modified. |
| Examples: |
Example 1 HTTPS POST: https://10.10.10.10:8440/ora/managementService/manage/ convertSession Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{ "requestParameters":
{
"sessionId": "AMS_10.10.10.10_1283550575777_2",
"conversionFormat": "mp4"
}
}
Response:
{
"responseMessage":"Success: Your request was
successfully completed.",
"responseCode":2000,
"responseBody":
{
"convertedLink":"http://10.10.10.10:8080/
oramedia/mp4/Session-1-10.10.10.10-
1283811989534.mp4"
}
}
|
|
Example 2—System Capacity Exceeded HTTPS POST: https://10.10.10.10:8440/ora/managementService/manage/ convertSession Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{ "requestParameters":
{
"sessionId": "AMS_10.10.10.10_1283550575777_2",
"conversionFormat": "mp4"
}
}
Response:
{
“responseCode”: 5006,
“responseMessage”: “Failure: Unable to convert the
session. Try again later.”,
"detail": "Capacity Exceeded"
}
|
deleteSessions
| Description: | Use this API to delete recorded sessions based on the specified
Session IDs.
You cannot delete an active session. If you try to delete an active session, you will receive an error message. |
| API URI: | https://<host>:<port>/ora/managementService/manage/deleteSessions |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters": {
"sessionIds": ["<replace with your
string>", "<replace with your
string>", ...]
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"jobId": "abcd1234"
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: |
Event type: sessionEvent Event action: deleted |
| Availability: | Available since API Version 1.0 |
| Release: | 8.5(1) |
| Notes: |
The jobId parameter in a successful response is used in the job query API to retrieve the job status and results. |
| Example: |
To delete multiple recordings: HTTPS POST: https://10.194.118.64:8440/ora/managementService/manage/ deleteSessions Headers: Content-Type: application/json Body:
{
"requestParameters": {
"sessionIds": [
"4ed31387d58902d1",
"4ed31387d58923a3"
]
}
}
Response:
{
"responseCode": 2000,
"responseMessage": "Successful",
"jobId": "abcd1234"
}
|
deleteSessionTag
| Description: |
Use this API to delete tags from a session. A tag is the name assigned by the user to label a recording. After you no longer need a label or tag, delete it from this session using this API. The tagName and tagOffset parameters are unique for a tag. When deleting a recording, make sure that you use the same name and offset fields with which it was created (using the addSessionTag API). After you delete a recording, you cannot undo this operation; but you can add the tag again to the session by specifying the tag name and offset fields. |
| API URI: | https://<host>:<port>/ora/managementService/manage/deleteSessionTag |
| Supported response formats: | JSON |
| HTTP method: | POST |
| Request parameters: |
{
"requestParameters":
{
"sessionId": "<replace with your string>",
"tagName": "<replace with
your string>",
"tagOffset": <replace with
your integer>
}
}
|
| Header parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseCode": 2000,
"responseMessage": "Successful"
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: |
Event type: tagEvent Event action: deleted |
| Availability: | Available since API Version 1.1 |
| Release: | 8.5(2) |
| Example: |
HTTPS POST: https://10.78.95.207:8440/ora/managementService/manage/ deleteSessionTag Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> Body:
{
"requestParameters":
{
"sessionId": "3212d734fd0a71",
"tagName": "demo",
"tagOffset": 10
}
}
Response:
{
"responseMessage":"Success: Your request was
successfully completed.",
"responseCode":2000
}
|
Session Query
Use these APIs to query the MediaSense system. The getSessions API supports advanced search using a combination of query criteria.
To perform a simple search (such as searching for sessions by only a deviceRef), use the simpler wrapper APIs.
getAllActiveSessions| Description: | Use this API to search all active recordings. The returned sessions are automatically sorted by sessionStartDate (in descending order). |
| API URI: | https://<host>:<port>/ora/queryService/query/getAllActiveSessions |
| Supported Response Formats: | JSON |
| HTTP Method: | GET |
| Request Parameters: | These parameters must be specified in the query section of the URL: |
| Header Parameters: | None |
| Parameter Description: |
See API Parameters. |
| Successful JSON Response Schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"responseBody": {
"sessions": [
{
"sessionId": "<this is a string>",
"callControllerIP": "<this is a string>",
"callControllerType": "<this is a
string>",
"ccid": "<this is a string>",
"sessionStartDate": "<this is an
integer>",
"sessionDuration": "<this is an integer>",
"sessionState": "<this is a string>",
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": "<this is an
integer>",
"tagOffset": "<this is an
integer>"
}
],
"tracks": [
{
"trackNumber": "<this is an
integer>",
"trackStartDate": "<this is an
integer>",
"trackDuration": "<this is an
integer>",
"trackMediaType": "<this is a
string>",
"downloadUrl": "<this is a
string>",
"codec": "<this is a string>",
"participants": [
|
{
"deviceRef": "<this is
a string>",
"participantStartDate":
"<this is an integer>",
"participantDuration":
"<this is an integer>",
"isConference": "<this
is a boolean>",
"xRefCi": "<this is a
string>",
"deviceId": "<this is a
string>"
}
],
"tags": [
{
"tagName": "<this is a
string>",
"tagType": "<this is a
string>",
"tagCreateDate": "<this
is an integer>",
"tagOffset": "<this is
an integer>"
}
]
}
],
"urls": {
"httpUrl": "<this is a string>",
"rtspUrl": "<this is a string>",
"mp4Url": "<this is a string>",
"wavUrl": "<this is a string>"
}
}
]
}
}
|
|
| Failure JSON Response Schema: |
{ "responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related Error Codes: |
See API Response Codes. |
| Events Triggered: | None |
| Availability: |
Available since API Version 1.0. Modified in API Version 1.2 Modified in API Version 1.4 Modified in API Version 1.5 See the following notes. |
| Release: | 8.5(1) |
| Notes: | |
| Examples: |
Example 1 To get all active sessions in the last 2 hours ending at 26 Jul 2012 20:45:40 GMT (for example, from 18:45:40 to 20:45:40): HTTPS GET: https://10.194.118.1:8440/ora/queryService/ query/getAllActiveSessions?maxSessionStartDate= 1343335540154 Headers: JSESSIONID: <the jsessionId received from a previous signIn request> |
|
Example 2 To get the first ten active sessions between 26 Jul 2012 18:45:40 GMT and 26 Jul 2012 20:45:40 GMT (2 hour time window): HTTPS GET: https://10.194.118.1:8443/ora/queryService/query/ getAllActiveSessions?offset=0&limit=10& minSessionStartDate=1343328340000&maxSessionStartDate =1343335540154 Headers: JSESSIONID: <the jsessionId received from a previous signIn request> |
getAllPrunedSessions
| Description: | Use this API to search all pruned recordings. The returned sessions are automatically sorted by sessionStart date. The term Pruned refers to recordings that are deleted by the MediaSense system. If you have explicitly deleted any recording using the deleteSessions API, then these deleted recordings, not pruned recordings. |
| API URI: | https://<host>:<port>/ora/queryService/query/getAllPrunedSessions |
| Supported Response Formats: | JSON |
| HTTP Method: | GET |
| Request Parameters: |
These parameters must be specified in the query section of the URL: |
| Header Parameters: | None |
| Parameter Description: |
See API Parameters. |
| Successful JSON Response Schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"responseBody": {
"sessions": [
{
"sessionId": "<this is a string>",
"callControllerIP": "<this is a string>",
"callControllerType": "<this is a
string>",
"ccid": "<this is a string>",
"sessionStartDate": "<this is an
integer>",
"sessionDuration": "<this is an integer>",
"sessionState": "<this is a string>",
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": "<this is an
integer>",
"tagOffset": "<this is an
integer>"
}
],
"tracks": [
{
"trackNumber": "<this is an
integer>",
"trackStartDate": "<this is an
integer>",
"trackDuration": "<this is an
integer>",
"trackMediaType": "<this is a
string>",
"downloadUrl": "<this is a
string>",
"codec": "<this is a string>",
"participants": [
|
{
"deviceRef": "<this is
a string>",
"participantStartDate":
"<this is an integer>",
"participantDuration":
"<this is an integer>",
"isConference": "<this
is a boolean>",
"xRefCi": "<this is a
string>",
"deviceId": "<this is a
string>"
}
],
"tags": [
{
"tagName": "<this is a
string>",
"tagType": "<this is a
string>",
"tagCreateDate": "<this
is an integer>",
"tagOffset": "<this is
an integer>"
}
]
}
],
"urls": {
"httpUrl": "<this is a string>",
"rtspUrl": "<this is a string>",
"mp4Url": "<this is a string>",
"wavUrl": "<this is a string>"
}
}
]
}
}
|
|
| Failure JSON Response Schema: |
{ "responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related Error Codes: |
See API Response Codes. |
| Events Triggered: | None |
| Availability: |
Available since API Version 1.0. Modified in API Version 1.2 Modified in API Version 1.4 Modified in API Version 1.5 See the following notes. |
| Release: | 8.5(1) |
| Notes: | |
| Examples: |
Example 1 To get all the pruned sessions in the last 2 hours ending at 26 Jul 2012 20:45:40 GMT (for example, from 18:45:40 to 20:45:40): HTTPS GET: https://10.194.118.1:8440/ora/queryService/query/ getAllPrunedSessions?maxSessionStartDate=1343335540154 Headers: JSESSIONID: <the jsessionId received from a previous signIn request> |
|
Example 2 To get the first ten pruned sessions between 26 Jul 2012 18:45:40 GMT and 26 Jul 2012 20:45:40 GMT (2 hour time window): HTTPS GET: https://10.194.118.1:8440/ora/queryService/query/ getAllPrunedSessions?offset=0&limit=10& minSessionStartDate=1343328340000&maxSessionStartDate= 1343335540154 Headers: JSESSIONID: <the jsessionId received from a previous signIn request> |
getAssociatedSessions
| Description: | Use this API to search and retrieve strongly associated sessions by a sessionID. The strongly associated sessions contain one xRefci in common.
|
||
| API URI: | https://<host>:<port>/ora/queryService/query/getAssociatedSessions | ||
| Supported Response Formats: | JSON | ||
| HTTP Method: | POST | ||
| Request Parameters: | {
"requestParameters":{
"sessionIdList" : [
"<replace with your string>"
]
}
}
|
||
| Header Parameters: | JSESSIONID | ||
| Parameter Description: | See API Parameters. |
||
| Successful JSON Response Schema: | {
"responseMessage":"Success: Your request was successfully completed.",
"responseCode":2000,
"responseBody":{
"sessions":[
{
"sessionState":"<this is a string>",
"callControllerType":"<this is a string>",
"sessionId":"<this is a string>",
"urls":{
"httpUrl":"<this is a string>",
"rtspUrl":"<this is a string>",
"mp4Url":"<this is a string>",
"wavUrl":"<this is a string>"
},
"sessionStartDate":"<this is an integer>",
"tracks":[
{
"trackStartDate":"<this is an integer>",
"trackDuration":"<this is an integer>",
"codec":"<this is a string>",
"downloadUrl":"<this is a string>",
"trackNumber":"<this is an integer>",
"trackMediaType":"<this is a string>",
"participants":[
{
"participantStartDate":"<this is an integer>",
"deviceRef":"<this is a an integer>",
"isConference":"<this is a boolean>",
"xRefCi":"<this is an integer>",
"participantDuration":"<this is an integer>",
"deviceId":"<this is a string>"
}
]
},
{
"trackStartDate":"<this is an integer>",
"trackDuration":"<this is an integer>",
"codec":"<this is a string>",
"downloadUrl":"<this is a string>",
"trackNumber":"<this is an integer>",
"trackMediaType":"<this is a string>",
"participants":[
{
"participantStartDate":"<this is an integer>",
"deviceRef":"<this is an integer>",
"isConference":"<this is a boolean>",
"xRefCi":"<this is an integer>",
"participantDuration":"<this is an integer>",
"deviceId":"<this is a string>"
}
]
}
],
"sessionDuration":"<this is an integer>",
"callControllerIP":"<this is a string>"
},
{
"sessionState":"<this is a string>",
"callControllerType":"<this is a string>",
"sessionId":"<this is a string>",
"urls":{
"httpUrl":"<this is a string>",
"rtspUrl":"<this is a string>",
"mp4Url":"<this is a string>",
"wavUrl":"<this is a string>"
},
"sessionStartDate":"<this is an integer>",
"tracks":[
{
"trackStartDate":"<this is an integer>",
"trackDuration":"<this is an integer>",
"codec":"<this is a string>",
"downloadUrl":"<this is a string>",
"trackNumber":"<this is an integer>",
"trackMediaType":"<this is a string>",
"participants":[
{
"participantStartDate":"<this is an integer>",
"deviceRef":"<this is an integer>",
"isConference":"<this is a string>",
"xRefCi":"<this is an integer>",
"participantDuration":"<this is an integer>",
"deviceId":"<this is a string>"
}
]
},
{
"trackStartDate":"<this is an integer>",
"trackDuration":"<this is an integer>",
"codec":"<this is a string>",
"downloadUrl":"<this is a string>",
"trackNumber":"<this is an integer>",
"trackMediaType":"<this is a string>",
"participants":[
{
"participantStartDate":"<this is an integer>",
"deviceRef":"<this is an integer>",
"isConference":"<this is a string>",
"xRefCi":"<this is an integer>",
"participantDuration":"<this is an integer>",
"deviceId":"<this is a string>"
}
]
}
],
"sessionDuration":"<this is an integer>",
"callControllerIP":"<this is a string>"
}
]
}
}
|
||
| Failure JSON Response Schema: | {
"responseCode": “<this is an integer>”,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
||
| Related Error Codes: | See API Response Codes. |
||
| Events Triggered: | none | ||
| Availability: | Available since API version 1.6 | ||
| Release: | 10.5 | ||
| Note: | The Call Association feature works by iterating through the stored recordings and searching for common xRefCi values. For example, if a conversation involves a call transfer from one agent (with BiB activated) to another agent (with BiB activated), the recording sessions generated will be linked to each other through a chain of common xRefCi values. The Call Association feature takes advantage of this and prepares a set of recording sessions which are thus related to each other.
|
||
| Example: | HTTPS POST: https://10.78.170.114:8440/ora/queryService/query/g etAssociatedSessions Headers: Content-Type: application/json Body: {
"requestParameters":{
"sessionIdList" : [
"514406fbae4a1"
]
}
}
Response: {
"responseMessage":"Success: Your request was successfully completed.",
"responseCode":2000,
"responseBody":{
"sessions":[
{
"sessionState":"CLOSED_NORMAL",
"callControllerType":"Cisco-CUCM",
"sessionId":"614406fbae5e1",
"urls":{
"httpUrl":"https://10.78.170.114:19443/recordedMedia/oramedia/mp4/614406fbae5e1.mp4",
"rtspUrl":"rtsp://10.78.170.114/archive/614406fbae5e1",
"mp4Url":"https://10.78.170.114:19443/recordedMedia/oramedia/mp4/614406fbae5e1.mp4",
"wavUrl":"https://10.78.170.114:19443/recordedMedia/oramedia/wav/614406fbae5e1.wav"
},
"sessionStartDate":1391686561,
"tracks":[
{
"trackStartDate":1391686561,
"trackDuration":78119,
"codec":"PCMU",
"downloadUrl":"http://10.78.170.114:8081/mma/ExportRaw?recording=614406fbae5e1-TRACK1",
"trackNumber":1,
"trackMediaType":"AUDIO",
"participants":[
{
"participantStartDate":1391686561,
"deviceRef":"1341051",
"isConference":false,
"xRefCi":"20248680",
"participantDuration":78119,
"deviceId":"SEP70F39517B88A"
}
]
},
{
"trackStartDate":1391686561,
"trackDuration":78119,
"codec":"PCMU",
"downloadUrl":"http://10.78.170.114:8081/mma/ExportRaw?recording=614406fbae5e1-TRACK0",
"trackNumber":0,
"trackMediaType":"AUDIO",
"participants":[
{
"participantStartDate":1391686561,
"deviceRef":"1341052",
"isConference":false,
"xRefCi":"20248679",
"participantDuration":78119,
"deviceId":"SEP402CF4ECA126"
}
]
}
],
"sessionDuration":78119,
"callControllerIP":"10.65.157.134"
},
{
"sessionState":"CLOSED_NORMAL",
"callControllerType":"Cisco-CUCM",
"sessionId":"514406fbae4a1",
"urls":{
"httpUrl":"https://10.78.170.114:19443/recordedMedia/oramedia/mp4/514406fbae4a1.mp4",
"rtspUrl":"rtsp://10.78.170.114/archive/514406fbae4a1",
"mp4Url":"https://10.78.170.114:19443/recordedMedia/oramedia/mp4/514406fbae4a1.mp4",
"wavUrl":"https://10.78.170.114:19443/recordedMedia/oramedia/wav/514406fbae4a1.wav"
},
"sessionStartDate":1391686561,
"tracks":[
{
"trackStartDate":1391686561,
"trackDuration":78093,
"codec":"PCMU",
"downloadUrl":"http://10.78.170.114:8081/mma/ExportRaw?recording=514406fbae4a1-TRACK1",
"trackNumber":1,
"trackMediaType":"AUDIO",
"participants":[
{
"participantStartDate":1391686561,
"deviceRef":"1341052",
"isConference":false,
"xRefCi":"20248679",
"participantDuration":78093,
"deviceId":"SEP402CF4ECA126"
}
]
},
{
"trackStartDate":1391686561,
"trackDuration":78093,
"codec":"PCMU",
"downloadUrl":"http://10.78.170.114:8081/mma/ExportRaw?recording=514406fbae4a1-TRACK0",
"trackNumber":0,
"trackMediaType":"AUDIO",
"participants":[
{
"participantStartDate":1391686561,
"deviceRef":"1341051",
"isConference":false,
"xRefCi":"20248680",
"participantDuration":78093,
"deviceId":"SEP70F39517B88A"
}
]
}
],
"sessionDuration":78093,
"callControllerIP":"10.65.157.134"
}
]
}
}
|
getSessionBySessionId
| Description: | Use this API to search and retrieve a recorded or live session by its session ID. |
| API URI: | https://<host>:<port>/ora/queryService/query/getSessionBySessionId |
| Supported Response Formats: | JSON |
| HTTP Method: | GET |
| Request Parameters: |
This parameter must be specified in the query section of the URL: value =<replace with your string> |
| Header Parameters: | None |
| Parameter Description: |
See API Parameters. |
| Successful JSON Response Schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"responseBody": {
"sessions": [
{
"sessionId": "<this is a string>",
"callControllerIP": "<this is a string>",
"callControllerType": "<this is a
string>",
"ccid": "<this is a string>",
"sessionStartDate": "this is an
integer>",
"sessionDuration": "this is an integer>",
"sessionState": "this is an integer>",
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": "this is an
integer>",
"tagOffset": "this is an integer>"
}
],
"tracks": [
{
"trackNumber": "this is an integer>",
"trackStartDate": "this is an
integer>",
"trackDuration": "this is an integer>",
"trackMediaType": "<this is a string>",
"downloadUrl": "<this is a string>",
"codec": "<this is a string>",
"participants": [
|
{
"deviceRef": "<this is a
string>",
"participantStartDate": "this
is an integer>",
"participantDuration": "this
is an integer>",
"isConference": "<this is a
boolean>",
"xRefCi": "<this is a string>",
"deviceId": "<this is a string>"
}
],
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": "this is an
integer>",
"tagOffset": "this is an
integer>"
}
]
}
],
"urls": {
"httpUrl": "<this is a string>",
"rtspUrl": "<this is a string>",
"mp4Url": "<this is a string>",
"wavUrl": "<this is a string>"
}
}
]
}
}
|
|
| Failure JSON Response Schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related Error Codes: |
See API Response Codes. |
| Events Triggered: | None |
| Availability: |
Available since API Version 1.2. Modified in API Version 1.4 Modified in API Version 1.5 See the following notes. |
| Release: | 8.5(3) |
| Notes: |
|
| Example: |
To get the session with the sessionId "13092154564622": HTTPS GET: https://10.194.118.1:8440/ora/queryService/query/ getSessionBySessionId?value=13092154564622 Headers: JSESSIONID: <the jsessionId received from a previous signIn request> |
getSessions
| Description: |
Use this API to search and retrieve recorded, live, or pruned sessions. Requirement: To enforce scalability, this API requires a sessionStartDate field condition. Limitation: This API stipulates that any kind of query is not possible. This limitation is due to the use of logical connectors between different parameters in the query. If you have three fields to query: f1, f2, and f3; and if the query is "f1=<query> and f2=<query> or f3=<query>", then SQL precedence rules are applied to the fields such that the query translates to: "[ ( f1=<query> and f2=<query> ) or (f3=<query> ) ]". Due to the use of brackets, f1 and f2 are computed first and the result of that computation is computed with f3. To summarize the limitation, a query like "[(f1) and (f2 or f3)]" is not possible. |
||
| API URI: | https://<host>:<port>/ora/queryService/query/getSessions | ||
| Supported Response Format: | JSON | ||
| HTTP Method: | POST | ||
| Request Parameters: |
{
"requestParameters": [
{
"fieldName" : "<replace with your string>",
"fieldConditions": [
{
"fieldOperator" : "<replace with your
string>",
"fieldValues": [
"<replace with your string>",
"<replace with your string>",
…
],
"fieldConnector": "<replace with your
string>" }
],
"paramConnector": "<replace with your string>" }
],
"pageParameters": {
"offset": "<replace with your string>",
"limit": "<replace with your string>" },
"sortParameters": [
{
"byFieldName": "<replace with your string>",
"order": "<replace with your string>" }
]
}
|
||
| Header Parameters: | JSESSIONID obtained from signIn API | ||
| Parameter Description: |
See API Parameters. |
||
| Successful JSON Response Schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"responseBody": {
"sessions": [
{
"sessionId": "<this is a string>",
"callControllerIP": "<this is a string>",
"callControllerType": "<this is a string>",
"ccid": "<this is a string>",
"sessionStartDate": <this is an integer>,
"sessionDuration": <this is an integer>,
"sessionState": "<this is a string>",
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": <this is an integer>,
"tagOffset": <this is an integer>
}
],
"tracks": [
{
"trackNumber": <this is an integer>,
"trackStartDate": <this is an integer>,
"trackDuration": <this is an integer>,
"trackMediaType": "<this is a string>",
"downloadUrl": "<this is a string>",
"codec": "<this is a string>",
"participants": [
|
||
{
"deviceRef": "<this is a string>",
"participantStartDate": <this is an integer>,
"participantDuration": <this is an integer>,
"isConference": "<this is a boolean>",
"xRefCi": "<this is a string>",
"deviceId": "<this is a string>"
}
],
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": <this is an integer>,
"tagOffset": <this is an integer>
}
]
}
],
"urls": {
"httpUrl": "<this is a string>",
"rtspUrl": "<this is a string>",
"mp4Url": "<this is a string>",
"wavUrl": "<this is a string>"
}
}
]
}
}
|
|||
| Failure JSON Response Schema: |
{
“responseCode”: <this is an integer>,
“responseMessage”: “Failure: <this is a string>”,
"detail": "<this is a string>"
}
|
||
| Related Error Codes: |
See API Response Codes. |
||
| Events Triggered: | None | ||
| Availability: |
Available since API Version 1.0 Modified in API Version 1.2 Modified in API Version 1.4 Modified in API Version 1.5 See the following notes. |
||
| Release: | 8.5(1) | ||
| Notes: |
|
||
|
|
|||
| Examples: |
Example 1 Query: Get all sessions where ( ( tagName = "foo" and sessionStartDate is between Nov 2, 2010 21:21:40 & Nov 3, 2010 21:21:40 ) or ( deviceRef = "1000" and sessionState = "active" ) ) HTTPS POST: https://10.194.118.1:8440/ora/queryService/query/getSessions Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> |
||
|
Body:
{
"requestParameters": [
{
"fieldName" : "tagName",
"fieldConditions": [
{
"fieldOperator" : "equals",
"fieldValues" : [
"foo"
]
}
],
"paramConnector": "AND"
},
{
"fieldName" : "sessionStartDate",
"fieldConditions": [
{
"fieldOperator" : "between",
"fieldValues" : [
1288732900000, // Tue, 02 Nov 2010
21:21:40 GMT
1288819300000 // Wed, 03 Nov 2010
21:21:40 GMT
]
}
],
"paramConnector": "OR"
},
{
"fieldName" : "deviceRef",
"fieldConditions": [
{
"fieldOperator" : "equals",
"fieldValues" : [
"1000"
]
}
],
"paramConnector": "AND"
},
{
"fieldName" : "sessionState",
"fieldConditions": [
{
"fieldOperator" : "equals",
"fieldValues" : [
"active"
]
}
]
}
]
}
|
|||
| Examples: |
Example 2 Query: Get all sessions where ( ( xRefCi = 12345678 and tagName = foo ) or ( sessionState = active and sessionStartDate is between Nov 2, 2010 21:21:40 & Nov 3, 2010 21:21:40 ) )
HTTPS POST: https://10.194.118.1:8440/ora/queryService/query/getSessions Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> |
||
|
Body:
{
"requestParameters": [
{
"fieldName" : "xRefCi",
"fieldConditions": [
{
"fieldOperator" : "equals",
"fieldValues" : [
"12345678"
]
}
],
"paramConnector": "AND"
},
{
"fieldName" : "tagName",
"fieldConditions": [
{
"fieldOperator" : "equals",
"fieldValues" : [
"foo"
]
}
],
"paramConnector": "OR"
},
{
"fieldName" : "sessionState",
"fieldConditions": [
{
"fieldOperator" : "equals",
"fieldValues" : [
"active"
]
}
],
"paramConnector": "AND"
},
{
"fieldName" : "sessionStartDate",
"fieldConditions": [
{
"fieldOperator" : "between",
"fieldValues" : [
1288732900000, // Tue, 02 Nov 2010
21:21:40 GMT
1288819300000 // Wed, 03 Nov 2010
21:21:40 GMT
]
}
]
}
]
}
|
|||
| Examples: |
Example 3 Query: Get all sessions where ( ( (deviceRef = "1000" or deviceRef="2000") or tagName="foo" ) and sessionState="active" ) A query where higher precedence is intended for an 'OR' operation over an 'AND' operation is not possible. |
||
| Examples: |
Example 4 Query: Get all sessions where ( deviceRef = "1000" and sessionStartDate is between Nov 2, 2010 21:21:40 & Nov 3, 2010 21:21:40 )
HTTPS POST: https://10.194.118.1:8440/ora/queryService/query/getSessions Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> |
||
|
Body:
{
"requestParameters": [
{
"fieldName" : "deviceRef",
"fieldConditions": [
{
"fieldOperator" : "equals",
"fieldValues" : [
"1000"
]
}
],
"paramConnector": "AND"
},
{
"fieldName" : "sessionStartDate",
"fieldConditions": [
{
"fieldOperator" : "between",
"fieldValues" : [
1288732900000, // Tue, 02 Nov 2010
21:21:40 GMT
1288819300000 // Wed, 03 Nov 2010
21:21:40 GMT
]
}
]
}
]
}
|
|||
| Examples: |
Example 5 Query: Get all sessions where a track has been recorded on nodeIPAddress "10.35.146.158" and partition "/common" between Nov 2, 2010 21:21:40 & Nov 3, 2010 21:21:40 HTTPS POST: https://10.194.118.1:8440/ora/queryService/query/getSessions Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> |
||
|
Body:
{
"requestParameters": [
{
"fieldName" : "nodeIPAddress",
"fieldConditions": [
{
"fieldOperator" : "equals",
"fieldValues" : [
"10.35.146.158"
]
}
],
"paramConnector": "AND"
},
{
"fieldName" : "partition",
"fieldConditions": [
{
"fieldOperator" : "equals",
"fieldValues" : [
"/common"
]
}
],
"paramConnector": "AND"
},
{
"fieldName" : "sessionStartDate",
"fieldConditions": [
{
"fieldOperator" : "between",
"fieldValues" : [
1288732900000, // Tue, 02 Nov 2010
21:21:40 GMT
1288819300000 // Wed, 03 Nov 2010
21:21:40 GMT
]
}
]
}
]
}
|
|||
| Examples: |
Example 6 Query: Get all sessions that have been pruned by the system between Nov 2, 2010 21:21:40 & Nov 3, 2010 21:21:40 Query: Get all sessions that have been pruned by the system between Nov 2, 2010 21:21:40 & Nov 3, 2010 21:21:40 HTTPS POST: https://10.194.118.1:8440/ora/queryService/query/getSessions Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> |
||
|
Body:
{
"requestParameters": [
{
"fieldName" : "pruned",
"fieldConditions": [
{
"fieldOperator" : "equals",
"fieldValues" : [
"true"
]
}
],
"paramConnector": "AND"
},
{
"fieldName" : "sessionStartDate",
"fieldConditions": [
{
"fieldOperator" : "between",
"fieldValues" : [
1288732900000, // Tue, 02 Nov 2010
21:21:40 GMT
1288819300000 // Wed, 03 Nov 2010
21:21:40 GMT
]
}
]
}
]
}
|
|||
| Examples: |
Example 7 Query: Get all sessions that lie within a certain date range, e.g. between Tue, 02 Nov 2010 21:21:40 GMT & Wed, 03 Nov 2010 21:21:40 GMT HTTPS POST: https://10.194.118.1:8440/ora/queryService/query/getSessions Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> |
||
|
Body:
{
"requestParameters": [
{
"fieldName" : "sessionStartDate",
"fieldConditions": [
{
"fieldOperator" : "between",
"fieldValues" : [
1288732900000, // Tue, 02 Nov 2010
21:21:40 GMT
1288819300000 // Wed, 03 Nov 2010
21:21:40 GMT
]
}
]
}
]
}
|
|||
| Examples: |
Example 8 Query: Get all sessions where ( (deviceRef = 1000 or deviceRef = 2000 or deviceRef = 3000) and sessionStartDate is between Nov 2, 2010 21:21:40 & Nov 3, 2010 21:21:40 ) ) HTTPS POST: https://10.194.118.1:8440/ora/queryService/query/getSessions Headers: Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request> |
||
|
Body:
{
"requestParameters": [
{
"fieldName": "deviceRef",
"fieldConditions": [
{
"fieldOperator": "equals",
"fieldValues": [
"1000"
],
"fieldConnector": "OR"
},
{
"fieldOperator": "equals",
"fieldValues": [
"2000"
],
"fieldConnector": "OR"
},
{
"fieldOperator": "equals",
"fieldValues": [
"3000"
]
}
],
"paramConnector": "AND"
},
{
"fieldName": "sessionStartDate",
"fieldConditions": [
{
"fieldOperator": "between",
"fieldValues": [
1288732900000, // Tue, 02 Nov 2010
21:21:40 GMT
1288819300000 // Wed, 03 Nov 2010
21:21:40 GMT
]
}
]
}
]
}
|
fieldOperators for getSessions
|
fieldName parameter |
Allowed fieldOperators for each fieldName parameter |
|---|---|
| tagName |
equals contains startsWith endsWith |
| tagType |
equals |
| deviceRef |
equals contains startsWith endsWith between |
| sessionState |
equals |
| sessionDuration |
lessThan greaterThan equals |
| mediaType |
equals |
| sessionStartDate |
between |
| xRefCi |
equals |
| pruned |
equals |
| partition |
equals |
| nodeIPAddress |
equals |
| ccid |
equals |
Enumerations for getSessions
| Parameter | Allowed enumerations for this parameter |
|---|---|
| byFieldName |
sessionId sessionState sessionDuration sessionStartDate ccid |
getSessionsByCCID
| Description: | Use this API to search and retrieve recorded or live sessions by Call Correlation Identifier (CCID). The returned sessions are automatically sorted by sessionStartDate, in descending order. | |
| API URI: | https://<host>:<port>/ora/queryService/query/getSessionsByCCID | |
| Supported Response Formats: | JSON | |
| HTTP Method: | GET | |
| Request Parameters: |
These parameters must be specified in the query section of the URL: |
|
| Header Parameters: | None | |
| Parameter Description: |
See API Parameters. |
|
| Successful JSON Response Schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"responseBody": {
"sessions": [
{
"sessionId": "<this is a string>",
"callControllerIP": "<this is a string>",
"callControllerType": "<this is a string>",
"ccid": "<this is a string>",
"sessionStartDate": "this is an integer>",
"sessionDuration": "this is an integer>",
"sessionState": "this is an integer>",
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": "this is an integer>",
"tagOffset": "this is an integer>"
}
],
"tracks": [
{
"trackNumber": "this is an integer>",
"trackStartDate": "this is an integer>",
"trackDuration": "this is an integer>",
"trackMediaType": "<this is a string>",
"downloadUrl": "<this is a string>",
"codec": "<this is a string>",
"participants": [
|
|
{
"deviceRef": "<this is a
string>",
"participantStartDate": "this
is an integer>",
"participantDuration": "this
is an integer>",
"isConference": "<this is a
boolean>",
"xRefCi": "<this is a string>",
"deviceId": "<this is a string>"
}
],
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": "this is an
integer>",
"tagOffset": "this is an
integer>"
}
]
}
],
"urls": {
"httpUrl": "<this is a string>",
"rtspUrl": "<this is a string>",
"mp4Url": "<this is a string>",
"wavUrl": "<this is a string>"
}
}
]
}
}
|
||
| Failure JSON Response Schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
|
| Related Error Codes: |
See API Response Codes. |
|
| Events Triggered: | None | |
| Availability: |
Available since API Version 1.2 Modified in API Version 1.4 Modified in API Version 1.5 See the following notes. |
|
| Release: | 8.5(3) | |
| Notes: |
The following changes were introduced in Release 10.0, Version 1.5: |
|
| Examples: |
Example 1 To get all sessions that have the ccid "0584071424-0000065536-0000000016-0671746570": HTTPS GET: https://10.194.118.1:8080/ora/queryService/query/ getSessionsByCCID?value=0584071424-0000065536-0000000016- 0671746570&offset=0&limit=0 Headers: JSESSIONID: <the jsessionId received from a previous signIn request> |
|
|
Example 2 To get the first ten sessions that have the ccid "0584071424-0000065536-0000000016-0671746570": HTTPS GET: https://10.194.118.1:8080/ora/queryService/query/ getSessionsByCCID?value=13092154564622%4010.194.118.71 &offset=0&limit=10 Headers: JSESSIONID: <the jsessionId received from a previous signIn request> |
||
|
Example 3 To get the first 100 (default number of records returned) sessions that have the ccid "0584071424-0000065536-0000000016-0671746570": HTTPS GET: https://10.194.118.1:8080/ora/queryService/query/ getSessionsByCCID?value=0584071424-0000065536-0000000016- 0671746570 Headers: JSESSIONID: <the jsessionId received from a previous signIn request>
|
getSessionsByDeviceRef
| Description: | Use this API to search and retrieve recorded or live sessions by Device Ref (the phone number, IP address, or URI/URL for each device). The returned sessions are automatically sorted by sessionStartDate (in descending order). |
| API URI: | https://<host>:<port>/ora/queryService/query/getSessionsByDeviceRef |
| Supported Response Formats: | JSON |
| HTTP Method: | GET |
| Request Parameters: |
These parameters must be specified in the query section of the URL: |
| Header Parameters: | None |
| Parameter Description: |
See API Parameters. |
| Successful JSON Response Schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"responseBody": {
"sessions": [
{
"sessionId": "<this is a string>",
"callControllerIP": "<this is a string>",
"callControllerType": "<this is a string>",
"ccid": "<this is a string>",
"sessionStartDate": "<this is an integer>",
"sessionDuration": "<this is an integer>",
"sessionState": "<this is a string>",
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": "<this is an integer>",
"tagOffset": "<this is an integer>"
}
],
"tracks": [
|
{
"trackNumber": "<this is an integer>",
"trackStartDate": "<this is an integer>",
"trackDuration": "<this is an integer>",
"trackMediaType": "<this is a string>",
"downloadUrl": "<this is a string>",
"codec": "<this is a string>",
"participants": [
{
"deviceRef": "<this is a
string>",
"participantStartDate": "<this
is an integer>",
"participantDuration": "<this
is an integer>",
"isConference": "<this is a
boolean>",
"xRefCi": "<this is a string>",
"deviceId": "<this is a string>"
}
],
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": "<this is an
integer>",
"tagOffset": "<this is an
integer>"
}
]
}
|
|
| Failure JSON Response Schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related Error Codes: |
See API Response Codes. |
| Events Triggered: | None |
| Availability: |
Available since API Version 1.0. Modified in API Version 1.2 Modified in API Version 1.4 See the following notes. |
| Release: | 8.5(1) |
| Notes: |
|
| Examples: |
Example 1 To get all sessions that have the deviceRef "1000" in the last 2 hours ending at 26 Jul 2012 20:45:40 GMT (for example, from 18:45:40 to 20:45:40): HTTPS GET: https://10.194.118.1:8440/ora/queryService/query/ getSessionsByDeviceRef?value=1000&maxSessionStartDate= 1343335540154 Headers: JSESSIONID: <the jsessionId received from a previous signIn request> |
|
Example 2 To get the first ten sessions that have the deviceRef "1000" between 26 Jul 2012 18:45:40 GMT and 26 Jul 2012 20:45:40 GMT (2 hour time window): HTTPS GET: https://10.194.118.1:8440/ora/queryService/query/ getSessionsByDeviceRef?value=1000&offset=0&limit= 10&minSessionStartDate=1343328340000&maxSessionStartDate= 1343335540154 Headers: JSESSIONID: <the jsessionId received from a previous signIn request> |
getSessionsByMediaType
| Description: | Use this API to search and retrieve recorded or live sessions based on the media type (audio, video, audio and video, or screen capture). The returned sessions are automatically sorted by sessionStartDate, with the most recent one being on the top. |
| API URI: | https://<host>:<port>/ora/queryService/query/getSessionsByMediaType |
| Supported Response Formats: | JSON |
| HTTP Method: | GET |
| Request Parameters: |
The following parameters must be specified in the query section of the URL: |
| Header Parameters: | None |
| Parameter Description: |
See API Parameters. |
| Successful JSON Response Schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"responseBody": {
"sessions": [
{
"sessionId": "<this is a string>",
"callControllerIP": "<this is a string>",
"callControllerType": "<this is a string>",
"ccid": "<this is a string>",
"sessionStartDate": "<this is an integer>",
"sessionDuration": "<this is an integer>",
"sessionState": "<this is a string>",
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": "<this is an integer>",
"tagOffset": "<this is an integer>"
}
],
"tracks": [
{
"trackNumber": "<this is an integer>",
"trackStartDate": "<this is an integer>",
"trackDuration": "<this is an integer>",
"trackMediaType": "<this is a string>",
"downloadUrl": "<this is a string>",
"codec": "<this is a string>",
"participants": [
|
{
"deviceRef": "<this is a string>",
"participantStartDate": "<this is an
integer>",
"participantDuration": "<this is an
integer>",
"isConference": "<this is a boolean>",
"xRefCi": "<this is a string>",
"deviceId": "<this is a string>"
}
],
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": "<this is an
integer>",
"tagOffset": "<this is an integer>"
}
]
}
],
"urls": {
"httpUrl": "<this is a string>",
"rtspUrl": "<this is a string>",
"mp4Url": "<this is a string>",
"wavUrl": "<this is a string>"
}
}
]
}
}
|
|
| Failure JSON Response Schema: |
{ "responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related Error Codes: |
See API Response Codes. |
| Events Triggered: | None |
| Availability: |
Available since API Version 1.0. Modified in API Version 1.2 Modified in API Version 1.4 Modified in API Version 1.5 See the following notes. |
| Release: | 8.5(1) |
| Notes: |
|
| Examples: |
Example 1 To get all sessions that have the mediaType "AUDIO" in the last 2 hours ending at 26 Jul 2012 20:45:40 GMT (for example, from 18:45:40 to 20:45:40): HTTPS GET: https://10.194.118.1:8440/ora/queryService/query/ getSessionsByMediaType?value=AUDIO&maxSessionStartDate= 1343335540154 Headers: JSESSIONID: <the jsessionId received from a previous signIn request> |
|
Example 2 To get the first ten sessions that have the mediaType "AUDIO" between 26 Jul 2012 18:45:40 GMT and 26 Jul 2012 20:45:40 GMT (2 hour time window): HTTPS GET: https://10.194.118.1:8440/ora/queryService/query/ getSessionsByMediaType?value=AUDIO&offset=0&limit= 10&minSessionStartDate=1343328340000&maxSessionStartDate= 1343335540154 Headers: JSESSIONID: <the jsessionId received from a previous signIn request> |
getSessionsByTag
| Description: | Use this API to search and retrieve recorded or live sessions based on the user-assigned tag names. A tag is the name a user assigns to label a recording. The returned sessions are automatically sorted by sessionStartDate (in descending order). |
| API URI: | https://<host>:<port>/ora/queryService/query/getSessionsByTag |
| Supported Response Formats: | JSON |
| HTTP Method: | GET |
| Request Parameters: |
The following parameters must be specified in the query section of the URL: |
| Header Parameters: | None |
| Parameter Description: |
See API Parameters. |
| Successful JSON Response Schema: |
{
"responseCode": 2000,
"responseMessage": "Successful",
"responseBody": {
"sessions": [
{
"sessionId": "<this is a string>",
"callControllerIP": "<this is a string>",
"callControllerType": "<this is a string>",
"ccid": "<this is a string>",
"sessionStartDate": "<this is an integer>",
"sessionDuration": "<this is an integer>",
"sessionState": "<this is a string>",
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": "<this is an integer>",
"tagOffset": "<this is an integer>"
}
],
"tracks": [
{
"trackNumber": "<this is an integer>",
"trackStartDate": "<this is an integer>",
"trackDuration": "<this is an integer>",
"trackMediaType": "<this is a string>",
"downloadUrl": "<this is a string>",
"codec": "<this is a string>",
"participants": [
|
{
"deviceRef": "<this is a string>",
"participantStartDate": "<this is an
integer>",
"participantDuration": "<this is an
integer>",
"isConference": "<this is a boolean>",
"xRefCi": "<this is a string>",
"deviceId": "<this is a string>"
}
],
"tags": [
{
"tagName": "<this is a string>",
"tagType": "<this is a string>",
"tagCreateDate": "<this is an
integer>",
"tagOffset": "<this is an integer>"
}
]
}
],
"urls": {
"httpUrl": "<this is a string>",
"rtspUrl": "<this is a string>",
"mp4Url": "<this is a string>",
"wavUrl": "<this is a string>"
}
}
]
}
}
|
|
| Failure JSON Response Schema: |
{ "responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related Error Codes: |
See API Response Codes. |
| Events Triggered: | None |
| Availability: |
Available since API Version 1.0 Modified in API Version 1.2 Modified in API Version 1.4 Modified in API Version 1.5 See the following notes. |
| Release: | 8.5(1) |
| Notes: |
|
| Examples: |
Example 1 To get all sessions that have the tag "mysampletag1" in the last 2 hours ending at 26 Jul 2012 20:45:40 GMT (for example, from 18:45:40 to 20:45:40): HTTPS GET: https://10.194.118.1:8440/ora/queryService/query/ getSessionsByTag?value=mysampletag1&maxSessionStartDate= 1343335540154 Headers: JSESSIONID: <the jsessionId received from a previous signIn request> |
|
Example 2 To get the first ten sessions that have the tag "mysampletag1" between 26 Jul 2012 18:45:40 GMT and 26 Jul 2012 20:45:40 GMT (2 hour time window): HTTPS GET: https://10.194.118.1:8440/ora/queryService/query/ getSessionsByTag?value=mysampletag1&offset=0&limit= 10&minSessionStartDate=1343328340000&maxSessionStartDate= 1343335540154 Headers: JSESSIONID: <the jsessionId received from a previous signIn request> |
Non-Scalable Queries
The getSessions API allows the client to perform custom queries on the metadata collected for each session. This API allows the client to form custom queries that can filter on any of several important data fields in the session metadata. It also provides a flexible way to combine those queries to perform powerful metadata searches.
 Note | If you misuse this custom query mechanism, it can have serious performance impacts on not only the query itself, but the entire MediaSense system. This is because it is possible to store large numbers of session records depending on the traffic on the system and the retention mechanism in use. This is normal. However, if a query processes a large amount of data, it could take up to several minutes to complete. It could also take resources away from the system that should be used to process new recordings and metadata. |
To avoid this problem, clients must form scalable queries. A scalable query is a query whose performance remains constant regardless of how much data is in the database. An example of a scalable query is: "Find all sessions whose start date/time is between 4 and 5 o'clock today." No matter how many sessions are in the database, the number of sessions between 4 and 5 o'clock today remain fairly stable and small. An example of a non-scalable query is: "Find all sessions." The number of sessions returned is proportional to the number of sessions in the database. If there are a large number of stored sessions, then the results are huge. It takes a lot of time to complete and impacts resources needed by other functions of the MediaSense system.
While there is no direct way to issue a "Find all sessions" query with the getSessions API, you can form a custom query to get almost the same result. For example, because all sessions have at least one track whose media type is "Audio," you could submit a query like: "Find all sessions whose media type is Audio." While this query cannot be prevented, it can be the source of serious performance impacts on the system. Although a specific value of media type is being specified ("Audio"), this is not restrictive enough. This is because most, if not all, sessions have a media type of "Audio." If there are a large number of sessions saved in the database, then the query has to process all these sessions. This is not scalable.
Note | It does not help to use pagination to specify a small page size. The page is obtained only after the full result set is processed. This is too late. |
A better approach is to reduce the scope of the query by reducing the number of sessions processed. In this case, perhaps what the client really wants is the last few sessions that occurred. You can do this by: "Find all sessions whose start date/time is greater than one hour ago." This returns a significantly smaller set of results. More importantly, it returns roughly the same number of sessions regardless of how many sessions are in the database. This is a scalable query.
If only the last 10 sessions are required, the client could also add the qualifier to sort the results on the start date/time field and specify pagination that displays the last 10 rows. Because the underlying result set is small, this is not a costly operation.
It is not always a problem to filter on media type. For example, the following query is quite scalable: "Find all sessions whose start date/time is during last Tuesday and whose media type is Video". First, narrow the overall result set by setting a time window. So the query has to search through only that small set of sessions to find the ones whose media type is "Video." In this case, the media type field does not affect scalability because it is combined with a scalable filter.
Different fields in the metadata have different degrees of scalability when used to filter sessions. Use the following table as a guide:
| Field name | Relative scalability | Notes |
|---|---|---|
| sessionId | Scalable | This value is unique. If you query for a session that has a specific id, you get only one. |
| sessionStartDate | Scalable | Use with care. If you specify an unreasonably large window size you still return a significant portion of the sessions in the database. Narrow the time window as much as possible. |
| maxSessionStartDate | Scalable | When used with minSessionStartDate this parameter allows you to specify the upper limit of a time window. Make sure you use a reasonably-sized window to limit the number of results. If this parameter is missing, then minSessionStartDate is required and the time window is assumed to be 2 hours. |
| minSessionStartDate | Scalable | When used with maxSessionStartDate this parameter allows you to specify the lower limit of a time window. Make sure you use a reasonably-sized window to limit the number of results. If this parameter is missing, then maxSessionStartDate is required and the time window is assumed to be 2 hours. |
| xrefCi | Scalable | This value is generally unique and takes a while to cycle. When filtering using a specific xrefCi value, you should get at most just a few sessions. |
| pruned | Mostly not scalable | This is a boolean field. If you select "false", you will likely get the vast majority of sessions in the database. Of course, if you select "true", the result set will be small and scalable. |
|
tagType sessionState mediaType |
Mostly not scalable | Only two to five possible values. For values like "Audio" for mediaType or "Completed" for sessionState the number of sessions returned is proportional to the number of sessions that are in the database. Of course, other values may return smaller result sets, but they will likely be proportional to the number of sessions in the database. |
| tagName | Not quite scalable | If tags are used, it is likely that the same tag names may be repeated across many sessions. To the degree that tags are used, the number of results returned that contain a specific tag may be proportional to the number of sessions in the database. |
| deviceRef | Not quite scalable | The extension numbers found in the deviceRef field tend to appear in many sessions. Numbers that are heavily used tend to be associated with a large number of sessions. This number may be proportional to the number of sessions in the database. |
| sessionDuration | Not quite scalable | Although the duration can vary somewhat, a simple query like "Find all session whose duration is less than 2 minutes" can return a large portion of the sessions in the database. |
| nodeIPAddress partition | Not scalable | The number of partitions or nodes is relatively small. So accessing the sessions associated with any specific partition or server (node) returns a number of sessions that is proportional to the number of sessions in the database. |
Field operators affect scalability. See the following table:
| Operator | Relative scalability | Notes |
|---|---|---|
| equals | Mostly scalable | If the field is scalable, then this usually returns a very small number of sessions. However, if the field is not scalable (for example, "mediaType equals Audio"), then this still returns a large portion of the sessions in the database. |
| between | Mostly scalable | Use with caution. For example, if the field is start date/time, but the start of the range is a date over a few years ago, you return the entire contents of the database. Be sure to keep the range narrow when using this operator. |
|
greaterThan lessThan |
It depends | If used to bracket the range of values and the range is sufficiently narrow, then these are scalable. However, if used alone, it is possible to return a large portion of the sessions in the database. |
|
contains startsWith endsWith |
Not so scalable | Even when used with a scalable field, these could cause a large portion of the sessions in the database to be returned. |
Field and parameter connectors affect scalability. See the following table:
| Connector | Relative scalability | Notes |
|---|---|---|
| and | Scalable | This connector narrows the scope of the filter so the result set generally gets smaller. |
| or | Not scalable | This connector widens the scope of the filter so the result set gets larger. This should be limited to connecting filters on scalable fields using scalable operators. |
When you define a query filter, always be sure to use a scalable filter. If you must filter on a non-scalable field, always use the "and" connector to connect it to a scalable filter that narrows the result set.
The following are a few examples of how client applications can use the MediaSense API effectively without impacting the performance of the system.
To track the progress of a session, a client application may take advantage of both the query and event mechanism of MediaSense. Initially the client must gather the state of the sessions it is interested in. This can be done by an initial query such as "Find all sessions containing extension number nnnn that are active that were started in the last day." This narrows the number of sessions to only those started in the last day and thus will be scalable. It then quickly finds the very small number of those sessions that contain the specified extension and that are active.
At the same time, the client should be subscribed to application events. This way, as the session changes state, the client can track its progress.
This is similar to the previous scenario. Make an initial query to establish the current set of active sessions: "Find all sessions that are active that started in the last day." One day should be plenty of time to ensure that you find all active sessions without taking too much system resources searching through all sessions in the database.
The client can continue to monitor the progress of the active sessions by using the event mechanism. If a new session is created, an event notifies the client so that it can begin to track it as well. Likewise when sessions close, they can be removed from the client's list of tracked sessions. The important point is that the client must do a major database query to initialize. This minimizes the impact to the system resources.
When a system is set up to use Recording Priority retention mode, the sessions are pruned based upon how long they were stored. However, the metadata associated with those sessions is not removed. It is preserved so that it may be reviewed by the administrator before it is deleted. The expected sequence is that the client application can request a list of "pruned" sessions. It may then display the metadata of interest from those sessions. Finally the user can select one or more of the pruned sessions to be deleted.
You can do the first step with a query like: "Find all sessions whose pruned status is 'true' that were started in the last two days." Use a reasonable time window to make the query scalable. Because the pruning uses an age-based mechanism, look at least a day prior to today. If this is not being done on a daily basis, you may want to limit the time window to about a day. This depends upon traffic at the site. You do not want the query returning more than about 100 sessions at a time. This may require some testing.
The client should then repeat this operation for each prior day until you have searched back to the last day you previously performed this operation. The client may then present the list to the user and ask that they select the sessions to be deleted (possibly giving a "delete all" option as well). The client uses the deleteSessions method of the API to submit a job to delete the selected sessions. There is no scalability issue in this case as the deleteSessions method serializes the deletion of each session.
To monitor the progress of the deletions, the client uses the event mechanism. As each session is deleted, a session event is generated with an event type of "deleted".
System Information
Use these APIs to obtain the MediaSense API version information. You do not need to sign in to use this API. The getAPIVersion API returns a floating point version number for the APIs running in MediaSense deployments.
getAPIVersion
| Description: | Use this API to retrieve the current version of the APIs running on the system. The version number starts at 1.0 and is not tied to the product version. The version number is x.y and not x.y.z (for example, it is 1.0 and not 1.0.1). |
| API URI: | https://<host>:<port>/ora/infoService/info/getAPIVersion |
| Supported response formats: | JSON |
| HTTP method: | GET |
| Request parameters: | None |
| Header parameters: | None |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseMessage": "Success: Your request was
successfully completed.",
"responseCode": 2000,
"responseBody": {
"apiVersion": "<this is string>"
}
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events Triggered: | None |
| Availability: | Available since API Version 1.0 |
| Release: | 8.5(1) |
| Example: |
HTTPS GET: https://10.10.10.10:8440/ora/infoService/info/ getAPIVersion Response:
{
"responseMessage": "Success: Your request was successfully completed.",
"responseCode": 2000,
"responseBody": {
"apiVersion": "1.4"
}
}
|
getSystemTime
| Description: |
Use this API to retrieve the current time of the system. The time is returned in milliseconds, since Jan 1, 1970 GMT. As all MediaSense servers are configured as NTP clients, any differences between them are expected to be small. Therefore only a single system time is returned, and this time applies to all servers in the MediaSense cluster. |
| API URI: | https://<host>:<port>/ora/infoService/info/getSystemTime |
| Supported response formats: | JSON |
| HTTP method: | GET |
| Request parameters: | None |
| Header Parameters: | JSESSIONID obtained from signIn API |
| Parameter description: |
See API Parameters. |
| Successful JSON response schema: |
{
"responseMessage": "Success: Your request was
successfully completed.",
"responseCode": 2000,
"responseBody": {
"currentSystemTime": <this is an integer>
}
}
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>",
"detail": "<this is a string>"
}
|
| Related error codes: |
See API Response Codes. |
| Events triggered: | None |
| Availability: | Available since API Version 1.1 |
| Release: | 8.5(2) |
| Notes: |
|
| Example: |
HTTPS GET: https://10.194.118.72:8440/ora/infoService/info/ getSystemTime Headers: JSESSIONID: <the jsessionId received from a signIn request> Response:
{
"responseMessage": "Success: Your request was
successfully completed.",
"responseCode": 2000,
"responseBody": {
"currentSystemTime": "1301145648258"
}
}
|
getSessionsResponseSchema
| Description: |
Use this API to retrieve the current version of the getSessions response schema running on the system. |
| API URI: | https://<host>:<port>/ora/infoService/info/getSessionsResponseSchema |
| Supported response formats: | JSON |
| HTTP method: | GET |
| Request parameters: |
None |
| Header Parameters: |
None |
| Parameter description: |
None |
| Successful JSON response: |
{
"type":"object",
"$schema": "http://json-schema.org/draft-03/schema",
"apiVersion": "string representation of api version",
"properties":
{"responseCode":
{"type":"number",
"required":true },
"responseMessage":
{"type":"string",
"required":true }
"responseBody":
{"type":"object",
"required":false
"properties":
{"sessions":
{"type":"array",
"required":true,
"items":
{"type":"object",
"required":true,
"properties":
{"callControllerIP":
{"type":"string",
"required":true },
"callControllerType":
{"type":"string",
"required":true },
"ccid":
{"type":"string",
"required":false,
"searchable":
{"operations": ["equals"] }
},
"sessionDuration":
{"type":"number",
"required":false,
"minimum":0,
"searchable":
{"operations": ["equals", "lessThan",
"greaterThan"] }
},
|
"sessionId":
{"type":"string",
"required":true },
"sessionStartDate":
{"type":"number",
"required":true,
"minimum":0,
"searchable":
{"operations": ["between"] }
},
"sessionState":
{"description":"string values are ACTIVE,
CLOSED_NORMAL, DELETED, and CLOSED_ERROR",
"type":"string",
"required":true,
"searchable":
{"operations": ["equals"] }
},
"tags":
{"type":"array",
"required":false,
"items":
{"type":"object",
"required":true,
"properties":
{"tagCreateDate":
{"type":"number",
"required":true },
"tagName":
{"type":"string",
"required":true,
"searchable":
{"operations": ["equals", "contains",
"startsWith", "endsWith"] }
},
"tagOffset":
{"type":"number",
"required":false },
"tagType":
{"description":"string values are
SYSTEM_DEFINED and USER_DEFINED",
"type":"string",
"required"true,
"searchable":
{"operations": ["equals"] }
}
}
},
|
|
"tracks":
{"type":"array",
"required":true,
"items":
{"type":"object",
"required":true,
"properties":
{"codec":
{"type":"string",
"required":true },
"downloadUrl":
{"type":"string",
"required":false },
"participants":
{"type":"array",
"required":true,
"items":
{"type":"object",
"required":true,
"properties":
{"deviceId":
{"type":"string",
"required":true },
"deviceRef":
{"type":"string",
"required":true,
"searchable":
{"operations": ["equals",
"contains", "startsWith",
"endsWith", "between"] }
},
"isConference":
{"type":"boolean",
"required":true },
"participantDuration":
{"type":"number",
"required":false },
"participantStartDate":
{"type":"number",
"required":true },
"xRefCi":
{"type":"string",
"required":false,
"searchable":
{"operations": ["equals"] }
}
}
}
},
|
|
"tags":
{"type":"array",
"required":false,
"items":
{"type":"object",
"required":true,
"properties":
{"tagCreateDate":
{"type":"number",
"required":true },
"tagName":
{"type":"string",
"required":true },
"tagOffset":
{"type":"number",
"required":false },
"tagType":
{"description":"string values are
SYSTEM_DEFINED and USER_DEFINED",
"type":"string",
"required":true, }
}
}
},
|
|
"trackDuration":
{"type":"number",
"required":false },
"trackMediaType":
{"description":"string values are AUDIO and
VIDEO",
"required":true,
"type":"string" },
"trackNumber":
{"type":"number",
"required"true },
"trackStartDate":
{"type":"number",
"required":true }
}
}
},
"urls":
{"type":"object",
"required":false,
"properties":
{"mp4Url":
{"type":"string",
"required":false },
"rtspUrl":
{"type":"string",
"required":false },
"wavUrl":
{"type":"string",
"required":false }
}
}
}
}
}
}
}
}
}
|
|
| Failure JSON response schema: |
{
"responseCode": <this is an integer>,
"responseMessage": "Failure: <this is a string>"
}
|
| Related error codes: |
Any HTTP failure scenarios (such as 404 or 500). See API Response Codes. |
| Events triggered: | None |
| Availability: | Available since API Version 1.5 |
| Release: | 10.0(1) |
| Notes: |
The "required" tag in the schema means that the parent property has to exist in the actual response. If "required" is not specified or it is set to false, then that property may not be returned by the response. MediaSense uses "searchable" a little differently than the json schema draft; the node consists of an object that is an array of all possible operations. If the "searchable" value exists, then the corresponding property is searchable. If it doesn't exist or is set to false, then the property is not searchable.The array defines properties (such as equals, greaterThan, lessThan, and between) by which the object is searchable. The between property has lowerBound and upperBound values. |
| Example: |
HTTPS GET: https://10.10.10.10:8440/ora/infoService/info/ getSessionsResponseSchema Response: See Successful JSON response schema above. |
API Parameters
MediaSense APIs use the term parameter to describe items with a name and value in JSON objects. We acknowledge that these items are referred to by various terms in different programming interfaces.
In the Description column of the following API parameter description tables, parameters are classified as follows:
- Required Input parameters are user-defined values, are necessary, and are supplied by the user to the system when the API or event is issued.
- Optional Input parameters are user-defined values and may be supplied by the user to the system when the API or event is issued. These parameter values are supplied only when users want to supply them.
- Output parameters have values that are system-generated and are the results of issuing the API or event. These values are calculated according to the input parameter values and the APIs or events that use them.
- API Parameter Description A to D
- API Parameter Description E to H
- API Parameter Description I to L
- API Parameter Description M to P
- API Parameter Description Q to T
- API Parameter Description U to Z
API Parameter Description A to D
API Parameter Description E to H
| Parameter | Which APIs or Events? | Description and Constraints | ||
|---|---|---|---|---|
| eventAction | Output string.
|
|||
| eventType | Output string. Events triggered for the corresponding MediaSense API. Enumeration values: |
|||
| fieldConditions | Required input. Array of strings. The conditions specified for the queried field. Specify multiple conditions for a field name. This parameter contains details on the fieldOperator, fieldValues, and fieldConnector. The enumeration values differ based on the APIs using this parameter. | |||
| fieldConnector | Optional input string when you have one field in an array. Required input string when you have two or more fields in an array. Used to logically connect a condition with the successive condition. See Precedence Rules. Enumeration values: |
|||
| fieldName | Required input string. The name of the queried field. The enumeration values differ based on the APIs using this parameter. | |||
| fieldOperator | Required input string. The logical operator conditions as specified
in the Values Expected for Each fieldOperator section. Permitted
number of operands for each operator:
|
|||
| fieldValues | Required input. Array of strings. The number of values passed in this array depends on the fieldOperator as specified in the Values Expected for Each fieldOperator section. This parameter does not accept regular expression ( *,+ and so on). The enumeration values differ based on the APIs using this parameter. | |||
| forwardedEvent | This field is omitted if events are locally-generated on the MediaSense server and if forwarding is disabled. Event forwarding
is disabled by default in MediaSense deployments. Enumeration
values: |
|||
| httpUrl | This parameter is deprecated in release 10 in favor of mp4Url. Output string. The HTTPS link for the session. Ther url is only present if the session state is CLOSED_NORMAL. The httpUrl parameter has a maximum of 512 characters.
|
API Parameter Description I to L
| Parameter | Which APIs or events? | Description and constraints |
|---|---|---|
| isConference | Output Boolean. Used within a Participant object. Indicates whether the participant is a conference bridge or an individual device. (Note: In certain scenarios, one participant may represent a conference bridge.) | |
| JSESSIONID | all APIs | Both an output string and a required input string. JSESSIONID is a header parameter. It is a session identifier and serves as a means of authentication for subsequent requests. The JSESSIONID expires when the user explicitly logs out or within 30 minutes of inactivity, whichever comes first. |
| job | JobResult | Output job object. Details for the job requested. |
| jobDuration | Output integer when getJobById or getJobResult is used. Optional input integer when getJobs is used. The time, in milliseconds, between the jobStartTime and the time when this job ends. | |
| jobId | Optional input string when getJobs is used. Output string when all other APIs or events in the list are used. The job created and managed by the job management framework. This jobID is system-generated. Use this jobID along with the Job management and Job query APIs. | |
| jobOperationsResultset | getJobResult | Output. Array of strings. Represents set of individual operations results for particular job. |
| jobState | Output string when getJobById or getJobResult is used. Optional input string when getJobs is used. After the job status is retrieved, the applicable value is pulled from the database based on the value at the time of polling. | |
| jobs | Output. Array of job objects. The list of jobs and the details for each job. | |
| jobStartTime | Output integer when getJobById or getJobResult is used. Optional input integer when getJobs is used. The time, in milliseconds, since Jan 1, 1970 GMT when this job started. The time when this job starts to execute. | |
| jobType | Output string when getJobById or getJobResult is used. Optional input string when getJobs is used. The purpose of the job. For example, deleting sessions in bulk. Case sensitive. Enumeration value is BULK_DELETE_SESSIONS. | |
| limit | Required input integer. The number of records to be returned, starting at the specified offset. Required within pageParameters. Must be used in conjunction with offset parameter. By default, it returns the first 100 records. Any positive value greater than zero (0). Maximum possible value for this parameter is 1000. |
API Parameter Description M to P
| Parameter | Which APIs or events? | Description and Constraints | ||
|---|---|---|---|---|
| maxSessionStartDate | Optional input integer. Becomes a required input integer when no value is specific for minSessionStartDate. The number of milliseconds since Jan 1, 1970 GMT when the session recording started, or more precisely, when the first track for this session began recording. If either minSessionStartDate or maxSessionStartDate is missing, it is assumed to be 2 hours in that direction. | |||
| mediaType | Output string. Required input string. Describes the type of media
being established. Case sensitive.
Enumeration values: |
|||
| mediaStreams | startRecording | Required input. Array of mediaTypes. The media streams being established. Each stream is a media type. Therefore, mediaStreams is an array of media types. A recording must have at least one media stream. The array is not ordered. | ||
| minSessionStartDate | Optional input integer. The number of milliseconds since Jan 1, 1970 GMT when the session recording started, or more precisely, when the first track for this session began recording. If either minSessionStartDate or maxSessionStartDate is missing, it is assumed to be 2 hours in that direction. | |||
| mp4Url | Output string. The mp4 link for the session. Maximim of 512
characters. The mp4Url is only present when the session state is
CLOSED_NORMAL and may return the following HTTPS Response Codes:
|
|||
| nodeId | storageThresholdEvent | Output integer. A system-assigned numeric value. You cannot define the nodeId because it is system-defined. | ||
| nodeIPAddress | Output string. The IP address of the Cisco MediaSense server. The nodeIPAddress parameter has a maximum of 54 characters. | |||
| offset | Optional input integer. Becomes a required input integer within pageParameters. The first record to be returned. Must be used in conjunction with limit parameter. The integer value starts at zero (0). | |||
| order | Optional input string. Becomes a required input string within
sortParameters. Case sensitive. Enumeration Values:
|
|||
| operationData | getJobResult | Output string. Optional input string. The individual operation input data in a job. Case sensitive. | ||
| operationID | getJobResult | Output string. Optional input string. The individual operation in a job. Case sensitive. | ||
| operationResponse | getJobResult | Output string. Optional input string. The individual operation response in a job. Case sensitive. | ||
| operationsCompleted | getJobById | Output integer. The number of operations completed for this job. This number vary depending on when this parameter is called. The counter starts at zero (0). | ||
| operationsRemaining | getJobById | Output integer. The number of operations remaining for this job. The number varies depending on when this parameter is called. | ||
| pageParameters | Optional input. JSON Object. Allows the client to request a specific subset of a request result representation. Specifies the elements to return. If used, it returns the first 1000 sessions. You must also specify the limit and offset parameters. See each parameter for related information. | |||
| paramConnector | Optional input string when you have only one field in the array.
Required input string when you have two or more fields in the
array. Used to specify the logical connection between two elements
in the RequestParameters array. Case sensitive. Enumeration values: |
|||
| partition | Output string. The name of the datastore using storage space. The partition parameter has a maximum of 128 characters. | |||
| participantDuration | Output integer. The number of milliseconds that the participant was
active in the session.
|
|||
| participants | Output JSON Array of participant objects. Each object in turn contains details on the deviceRef, participantStartDate, participantDuration, isConference, and the xRefCi parameters. See each of these parameter for related information. | |||
| participantStartDate | Output integer. The number of milliseconds since Jan 1, 1970 GMT when this track's recording started. | |||
| password | signIn | Required input string. Case sensitive. The password for the Unified Communications Manager user who is provisioned as a MediaSense user. All Unified Communications Manager password restrictions apply. Because Unified Border Element uses SSH authentication, MediaSense uses Unified Communications Manager authentication for all MediaSense users. | ||
| percentageUtilization | storageThresholdEvent | Output integer. The percentage of storage disk space used by recorded media. See the Storage Threshold Values section for details on percentage triggers. | ||
| pruned | getSessions | Output Boolean. Optional input Boolean. Indicates whether a session
was deleted by the system. The sessions that are deleted by a user
are not considered pruned. Pruned is omitted when a session has not
been deleted.
Enumeration values:
|
API Parameter Description Q to T
| Parameter | Which APIs or Events? | Description and Constraints | ||
|---|---|---|---|---|
| responseCode | all APIs | Output integer. The corresponding error code. | ||
| responseMessage | all APIs | Output string. A description of the responseCode for troubleshooting purposes. These descriptions are subject to change. | ||
| rtspUrl | Output string. A reference to the entire session, which can
contain multiple tracks. To access a particular track, suffix the rtspUrl with
"-TRACK0" or "-TRACK1". Both tracks in a given session open and close
simultaneously. URLs stay constant for the life of the session. The httpUrl
parameter has a maximum of 512 characters. Enumeration values:
|
|||
| sessions | Output. JSON array of session objects. Each object contains values for sessionId, tracks, URLs, sessionStartDate, and sessionDuration. See each parameter for related information. | |||
| sessionDuration | Output integer. The number of milliseconds that the session
lasted.
|
|||
| sessionId | The parameter sessionId is a system-generated identifier for a
session. Its value is unique across all MediaSense servers and has a maximum of
128 characters. A session is a unit of the capture service, where one session
is converted into one MP4 file.
Required input string for startRecording, stopRecording, addSessionTag, convertSession, and getSessionBySessionId. Output string for the remaining APIs and events. |
|||
| sessionIdList | getAssociatedSessions | The parameter sessionIdList accepts a list of multiple comma-separated sessionIds in the request body, but currently, only the first sessionId will be considered to return the strongly associated sessionIds. Additional sessionIds will be ignored. This input parameter has been made of the List type for future enhancement. |
||
| sessionIds | deleteSessions | Output list of session IDs. | ||
| sessionStartDate | Output integer for all APIs and events.
Required input integer for getSessions. The number of milliseconds since Jan 1, 1970 GMT when the session recording started, or more precisely, when the first track for this session began recording. |
|||
| sortParameters | Optional input. JSON array. This ordered array specifies how the returned result should be sorted. If the sorting is not specified, the default sorting is by the startDate with the newest session first. | |||
| sessionState | Output string. The state of the session. Enumeration values:
|
|||
| subscriptionFilters |
Output JSON array and an optional input JSON array. This array specifies a list of events or a list of event categories. Depending on which API it is used in, its meaning varies. |
|||
|
|
||||
|
The client can use the category name or the specific event names. If a category is used, the client is subscribed to all events in that category. |
||||
| subscriptionId | Output string for subscribeToEvents.
Required input string for all other APIs and events in the list. The parameter subscriptionId is the system-generated ID that is received from the subscribeRecordingEvent API. |
|||
| subscriptionStatus | Output string. The response that is received from the
verifyEventSubscription API or the verifyRecordingSubscription API. Enumeration
Values:
|
|||
| subscriptionType | Output string. Type of subscription. For server-based clients, the type is HTTP. | |||
| subscriptionUri | Required input string. The URI where event notifications are sent to server-based clients. The subscription is keyed by the subscriptionUri parameter. Only one subscription is allowed for any given subscriptionUri. | |||
| tags | Output. JSON array of tag objects. Each object includes information on the tagName, tagType, tagCreateDate, and tagOffset parameters. The tag parameter has a maximum of 255 characters. | |||
| tagCreateDate | Output integer. The number of milliseconds since Jan 1, 1970 GMT when this tag was created. | |||
| tagName | Output string. The name that is used to label a recording, which
is not case sensitive. This parameter has a maximum limit of 255 characters. If
tagtype = SYSTEM_DEFINED, then the enumeration values for tagName are as
follows:
|
|||
| tagNameRegEx | Optional input string. A Java regular expression which only applies to tag events. This string is additive, that is, MediaSense only sends a tagEvent to the subscriber when the event matches the actions that are requested by the subscriber and when the tagName matches the subscriber's optional regular expression specified by this parameter. See http://download.oracle.com/javase/tutorial/essential/regex/ for more information on Java regular expressions. | |||
| tagOffset | Optional integer for addSessionTag. The number of milliseconds from the start of session for this tag. Use tagOffset to specify a point in the recording. (For example, at the 10th second from the beginning of a specific recording, an unexpected event occurred.) It is an output integer for all other APIs and events in the list. The offset is calculated from the start of the session or track (regardless of the tag being present at the track level or the session level). If no offset is specified, the tag is applied to the entire session and not to any specific point in the session. | |||
| tagType | Output string. Enumeration values:
|
|||
| trackDuration | Output integer. The number of milliseconds that the track
lasted.
|
|||
| trackMediaType | Output integer. Enumeration Values:
|
|||
| trackNumber | Output integer. The system-generated unique identifier of the
track.
For Unified Communications Manager, track 0 contains media streamed from the forking device and track 1 contains media streamed to the forking device. In a Unified Comminications Manager sessionEvent, each track is associated with one or more participants generating the media for each track. For Unified Border Element, The trackNumber assignment is arbitrary and is not based on forking devices. The order in which elements appear in the track array is arbitrary and has no particular meaning. |
|||
| tracks | Output. JSON array of track objects. Each object in turn includes information on the trackNumber, trackStartDate, trackDuration, trackMediaType, and participants parameters. | |||
| trackStartDate | Output integer. The number of milliseconds since Jan 1, 1970 GMT when the track recording started (when the Call Control Service received the 200 OK message from Unified Communications Manager or Unified Border Element). MediaSense sends an acknowledgment (ACK) back to Unified Communications Manager or Unified Border Element accordingly. |
API Parameter Description U to Z
| Parameter | Which APIs Events? | Description and Constraints | ||
|---|---|---|---|---|
| urls | Output. JSON object. Includes information on the httpUrl and the rtspUrl parameters. | |||
| username | signIn | Required input string. The Unified Communications Manager user who is provisioned as a MediaSense user. Unified Communications Manager uses "User ID" while MediaSense uses username (non case-sensitive). All Unified Comminications Manaer User ID restrictions apply. Because Unified Border Element uses SSH authentication, MediaSense uses Unified Communications Manager authentication for all MediaSense users. | ||
| wavUrl | Output string. The wav link for the session. Maximum of 512
characters. For Sessions that also include video tracks, the
wavUrl will only contain the audio tracks. The wavUrl is only
present when the session state is CLOSED_NORMAL and may return the
following HTTPS Response Codes:
|
|||
| xRefCi | The Unified Communications Manager identifier for a particular media stream. All APIs and events in the list are output strings; getSessionsByCCID is both an output string and an optional input string. These APIs and events do not always correspond one-to-one with the recorded tracks. However, you must use this identifier to correlate the Unified Communications Manager JTAPI events to recorded sessions. xRefCi is present when the callControllerType for a session = "Cisco-SIPGateway" or "Cisco-Unified Communications Manager". xRefCi is omitted when callControllerType = "direct". Unified Border Element does not use this identifier. |
Job States
| Job States | Description |
|---|---|
| RUNNING | The job started execution successfully and continues to execute. |
| COMPLETED | The job completed successfully. Note: 'completed successfully' does not mean all operations are successful, it just indicates that all operations in this job were attempted successfully. |
| CANCELED | The job was canceled using the cancelJob API and is no longer running. |
| ERROR | The job stopped executing because of a system error. |
Precedence Rules for paramConnector and fieldConnector
| Rule # | Details | Description | Query Translation | Example |
|---|---|---|---|---|
| 1 | Multiple conditions on the same field get the highest logical precedence. | One field can have multiple conditions specified on it, in the requestParameters array. | This query translates to: |
deviceRef=1000 or deviceRef=2000 and tagName=foo or state=active Using the precedence rule'and' takes precedence over 'or' , the query translates to #2 above, not #1. |
| 2 | Precedence of 'and' over 'or'. | The Param connectors are used to connect two or more fields in a logical manner. Now if there are 3 or more fields connected together by different connectors, then we need to know what takes higher precedence. | This query can be ambiguous in the sense that it can mean either: |
tagName = tagName1 or deviceRef = 1000 and state = active Using the precedence rule'and' takes precedence over 'or' , the query translates to #2 above, not #1. |
API Response Codes
2xxx Success Response Codes
The action was successfully received, understood, and accepted.
| Response Code | Description |
|---|---|
| 2000 | Success: Your request was successfully completed. |
| 2001 | Success: No results found for this client request. |
| 2002 | Success: The session recording was successfully paused but the database could not be updated. |
| 2003 | Success: The session recording was successfully resumed but the database could not be updated. |
| 2004 | Success: The session recording was successfully deleted but the database could not be updated. |
| 2005 | Success: The subscription with the given subscriptionUri already exists. |
| 2006 | Success: The current subscription has been updated and has been unsubscribed from the subscriptionFilters requested. The subscription is still active. |
3xxx Redirection Response Code
The client must take additional action to complete the request.
| Response Code | Description |
|---|---|
| 3001 | Failure : Unable to process the request. Provide redirection and try again. |
4xxx Client Error Response Codes
The request contains bad syntax or cannot be fulfilled.
| Response Code | Description |
|---|---|
| 4000 | Failure: Your request is invalid. |
| 4001 | Failure: Unsecured HTTP is not allowed. Use HTTPS for your request. |
| 4005 | Failure: Cannot find value in database. Detail: <parameter name>: <parameter value> |
| 4019 | Failure: Not an authorized MediaSense user. |
| 4020 | Failure: Your login credentials (username or password) are invalid. |
| 4021 | Failure: Invalid session. The session may have expired. Sign in again or enter a valid JSESSIONID. |
| 4022 | Failure: The specified user is not a Finesse supervisor. |
| 4023 | Failure: Connection to the Cisco Finesse server failed. Verify the Cisco Finesse configuration and try again. |
| 4030 | Failure: Unable to establish a call using this deviceRef. Verify the deviceRef and try again. |
| 4031 | Failure: The deviceRef is unavailable or busy. Verify the device and try again later. |
| 4032 | Failure: Unable to disconnect the call using this deviceRef. Verify if the call exists and try again. |
| 4033 | Failure: Unsupported combination of mediaStreams. Verify the allowed streams for this parameter and try again. |
| 4041 | Failure: The fieldName parameter is invalid. |
| 4042 | Failure: The fieldOperator parameter is invalid. |
| 4043 | Failure: The number of fieldValue parameters is invalid. |
| 4045 | Failure: The connector parameter is invalid. |
| 4046 | Failure: The order parameter is invalid. |
| 4047 | Failure: The fieldName parameter is missing. |
| 4048 | Failure: The fieldCondition parameters are missing. |
| 4049 | Failure: The fieldOperator parameter is missing. |
| 4050 | Failure: The fieldValue parameters are missing. |
| 4051 | Failure: The fieldConnector parameter is missing. |
| 4052 | Failure: The paramConnector parameter is missing. |
| 4053 | Failure: The fieldName parameter is missing. Unable to sort by fieldName. |
| 4054 | Failure: The order parameter is missing. |
| 4055 | Failure: The requestParameter is missing. |
| 4056 | Failure: Invalid JSON syntax. Verify the syntax and try again. |
| 4057 | Failure: One or more of the fieldValue parameters are of the incorrect type. |
| 4058 | Failure: Missing tagName parameter. |
| 4059 | Failure: The authentication provider is invalid. Valid authentication providers are: AXL, FINESSE |
| 4060 | Failure: The value is missing in the client request. |
| 4061 | Failure: Missing parameter in message. Detail: <parameter name> |
| 4062 | Failure: Invalid syntax in parameter. Detail: <parameter name> |
| 4063 | Failure: The offset parameter is invalid. |
| 4064 | Failure: The limit parameter is invalid. |
| 4070 | Failure: The sessionId is invalid or no active session is found. |
| 4071 | Failure: The sessionId is invalid or no inactive session is found. |
| 4072 | Failure: The sessionId is invalid or no session is found. |
| 4073 | Failure: The conversionFormat is invalid. Please verify the supported formats and try again. |
| 4080 | Failure: The subscription with the given subscriptionUri already exists. |
| 4081 | Failure: The subscription with the given subscriptionId does not exist. |
| 4082 | Failure: Unable to convert a session that is in the ACTIVE or ERROR state. |
| 4090 | Failure: The jobId is invalid or particular job is not running at this moment. |
5xxx Server Error Response Codes
The server failed to fulfill an apparently valid request.
| Response Code | Description |
|---|---|
| 5000 | Failure: An unknown server error occurred. Try again later. |
| 5001 | Failure: A database error occurred. Try again later. |
| 5002 | Failure: Unable to pause the session. Try again later. |
| 5003 | Failure: Unable to resume the session. Try again later. |
| 5004 | Failure: Unable to delete the session. Try again later. |
| 5006 | Failure: Unable to convert the session. Try again later. Detail: <Reason For Failure> |
| 5020 | Failure: AXL service on the Unified Communications Manager timed out. Try again later. |
| 5021 | Failure: AXL service on the Unified Communications Manager is not activated. Activate the service and try again. |
| 5022 | Failure: AXL credentials are invalid. Verify the Unified Communications Manager configuration and try again. |
| 5023 | Failure: Unknown AXL Host. Verify the Unified Communications Manager configuration and try again. |
| 5024 | Failure: Unknown AXL service error. Try again later. |
| 5025 | Failure: Connection to the AXL service failed. Try again later. |
| 5030 | Failure: Unable to establish a call using this DeviceRef in association with the system. Verify the Unified Communications Manager or Unified Border Element system and try again. |
| 5031 | Failure: Unable to record the call. Verify that the MediaSense Media Service is functioning and try again. |
| 5032 | Failure: Unable to record the call. Low disk space on MediaSense Media Service. |
| 5040 | Failure: Unable to process the request. Invalid state of the job for the requested operation. Verify the job state and try again. Detail: <Job State> |
| 5041 | Failure: Request timed out. Resubmit your request. |
| 5042 | Failure: The system has exceeded the maximum number of concurrent requests. Try again later. |
Feedback