V-Spark Online Help

Sample /config/folders JSON Output for a Folder

The following JSON shows sample output for a single folder from the information retrieved via the /config/folders API.

Figure 1. Sample Folder output from the /config/folders API
"DocTestCo": {
    "DocTestCo-DocTesting": {
        "Test01": {
            "apps": [],
            "asroptions": {
                "billing": "customerX"
            },
            "audiotype": "Mono",
            "callback": {
                "aws_id": "123456789012345678901",
                "aws_secret": "123456789012345678901/12345678901234567890",
                "posturl": "S3:///joeuser/test",
                "sendaudio": "no",
                "sendtext": "no"
            },
            "created": "2017-05-18",
            "custom_meta": [],
            "mode": "active",
            "modelchan0": "eng1:callcenter",
            "nspeakers": 1,
            "purifyaudio": true,
            "purifytext": true,
            "status": "OK",
            "servers": [
                "asrsrvr1"
            ]
        },...
    },...
},...


When creating a new folder using the /config/folders API, all fields that are not read-only are required.

Table 1. /config/folders Fields

Name

Type

Values

Description

apps

Applications that are linked to this folder that will analyze this folder's content.

"apps": [],

asroptions

ASR stream tags that have been added to this folder. Tags are parameters that affect transcription requests.

"asroptions": {
    "billing": "customerX"
},

audiotype

REQUIRED when creating a new folder

Whether the audio is two-channel ("Stereo") or single-channel ("Mono") audio.

"audiotype": "Mono",

callback

Callback options for transcript delivery. For more information on using callbacks, see Using Callbacks in V‑Spark.

"callback": {
    "aws_id": "123456789012345678901",
    "aws_secret": "123456789012345678901/12345678901234567890",
    "posturl": "S3:///joeuser/test",
    "sendaudio": "no",
    "sendtext": "no"
},

posturl

The path that V‑Spark will use to deliver transcripts and other information. This URL must start with a valid protocol, (such as "http://", "https://", "file://", "sftp://", or "s3://") and include any needed hostname, port number, and file system path.

aws_id

REQUIRED if posturl is set to an "s3://" URL.

Your AWS access key id.

aws_secret

REQUIRED if posturl is set to an "s3://" URL.

Your AWS secret access key.

username

REQUIRED if posturl is set to an "sftp://" URL and sshprivatekey is not set.

The username on the remote system that V‑Spark should use to log in.

password

REQUIRED if posturl is set to an "sftp://" URL, and sshprivatekey is not set.

The login password of the username account on the remote system,

sshprivatekey

REQUIRED

The ssh private key of the username account on the remote system This setting is REQUIRED ifposturl is set to an "sftp://" URL, and username & password are not set.

sendaudio

REQUIRED if posturl is set.

yes, no

If set to "yes," V‑Spark will send an MP3 version of the transcribed audio file to the callback server.

sendtext

REQUIRED if posturl is set.

yes, no

If set to "yes," V‑Spark will send a plain text version of the transcribed audio file to the callback server.

created

READ-ONLY Date, in YYYY-MM-DD format

The date that the folder was created. This field is added by V‑Spark when the folder is created, and is read-only.

"created": "2017-05-18",

custom_meta

Custom metadata fields that are associated with this folder.

"custom_meta": [
    "client name",
    "phone number"
],

mode

active (default), paused

The mode field in the JSON output for a Folder indicates whether processing of that folder is "active" or "paused." Use the /config/folders API to pause and resume processing of the folder. Pause the processing of a Folder by POSTing a JSON configuration file for the Folder that has the mode property of the Folder set to the value paused. Resume processing by POSTing JSON for the Folder that has the mode property set to active. You will not be able to set Folder processing to active if the Folder has been paused due to company-level policies such as the processing hours limit being met.

"mode": "active",

modelchan0

Acceptable values are limited to the names of the language models you are licensed to use. All language models work with all supported audio formats.

The language model to use when processing audio on Channel 0, which is the left channel if you are processing stereo audio.

"modelchan0": "eng1:callcenter",

modelchan1

Acceptable values are limited to the names of the language models you are licensed to use. All language models work with all supported audio formats.

The language model to use when processing audio on Channel 1, which is the right channel if you are processing stereo audio. If this folder is not configured to process stereo audio, you will not have a modelchan1.

"modelchan1": "spa1:callcenter",

agentchan

If this folder is configured to process stereo audio, the value of this field must be either "0" or "1," indicating the audio channel that contains agent speech.

"agentchan": "0",

nspeakers

REQUIRED when creating a new folder.

The number of speakers in the audio files that are going to be placed into the folder.

This option cannot be modified after the folder is created.

"nspeakers": 1,

purifyaudio

Boolean

true, false

If set to "true," processing cleans the generated audio MP3 of any locations where numbers exist for Payment Card Information (PCI) or other sensitive numbers that are in the audio source so that these numbers cannot be heard. If set to "false," audio is not scrubbed.

This option cannot be modified after the folder is created.

"purifyaudio": true,

purifytext

Boolean

true, false

If set to "true," processing cleans the text transcript of any numbers for Payment Card Information (PCI) or other sensitive numbers that are in the audio source. If set to "false," text is not scrubbed.

This option cannot be modified after the folder is created.

"purifytext": true,

status

High-level status information about the folder, useful for long-running operations such as a DELETE.

A status of "OK" indicates that any operations on the folder have completed their work.

"status": "OK",

servers

The name(s) of the V‑Spark servers that will be used for ASR.

You must specify at least one server or vcloud:cloudtoken statement.

"servers": [
                  "asrsrvr1"


For more information about the information that is part of the definition of a folder, see the Creating a Folder section in the V‑Spark Management Guide.

The excerpt from the output of calling the /config/folders API shown previously is very similar to the output that you would have received had you requested information about a single folder by calling an API URL such as the /config/DocTestCo/DocTestCo-DocTesting/Test01 API on a V‑Spark installation where the "Doc Test Co" company, the "Doc Testing" organization, and the folder "Test01" (with the company short name, "DocTestCo," the Organization short name of "DocTestCo-DocTesting," and the folder name of "Test01") had been defined.

The latter call would have returned JSON like the sample below, which differs only from the output shown previously in that it does not need to identify the short name of the company, the short name of the organization, or the name of the folder that it refers to because they are specified in the URL.

Figure 2. Sample Folder output from the /config/CO_SHORT/ORG_SHORT/FOLDERNAME API
{
    "apps": [],
    "asroptions": {
        "billing": "DocTestCo-DocTesting-Test01"
    },
    "audiotype": "Mono",
    "callback": {
        "aws_id": "0SAMPLEVALUED0N0TUSE",
        "aws_secret": "ThisIsAlsoASample000/NotARealAWSSecret00",
        "posturl": "S3:///wvh/test",
        "sendaudio": "no",
        "sendtext": "no"
    },
    "created": "2017-05-18",
    "custom_meta": [],
    "mode": "active",
    "modelchan0": "eng1:callcenter",
    "nspeakers": 1,
    "purifyaudio": true,
    "purifytext": true,
    "servers": [
        "asrsrvr1"
    ]
}