Understanding & Constructing Dynamic CVP Elements with VFC: Part 1

Our Goal today is to construct a CVP Element that will consume an input string and by using the TTS engine on the Developers box will output audio for our test call.
Cisco provides a number of examples of ways to create simple Dynamically configurable elements, you can find a number of them on the Cisco DevNet space for CVP. Cisco also provides Programming Guides for the CVP and Element Specifications (I am linking articles pertaining to CVP 11.0 for simplicity).
We will be making use of the Voice Foundation Classes or 'VFC' to construct the VXML content for our Element but before we dive deep into VXML we start we are going to need to create a java class that defines our custom element.

public class MyCustomDynamic_Element extends VoiceElementBase implements ElementInterface {

}

As you can see we are Implementing the ElementInterface class and Extending the VoiceElementBase class.
Next, we are going to need to define the name of our element, its description and the name of the folder that we are going to put our Element within when it's in the Call Studio Builder.

public String getElementName() { return "MyCustomDynamic_Element"; }
public String getDescription() { return "Does cool dynamic media stuff."; }
public String getDisplayFolderName() { return "MyCompanyName"; } 

As I stated before we are going to want to consume a String for our new element, for us to be able to set what that String is going to be within the Builder we are going to need to define some Settings by adding the getSettings() function to our class.

public Setting[] getSettings() throws ElementException {
Setting myStringData = new Setting("myStringData", "myStringData", "myStringData", true, true, true, Setting.STRING);
Settin myExample = new Setting("myExample", "myExample", "myExample", true, true, true, Setting.STRING);Setting[] cfg_settings = new Setting[] { myStringData, myExample };
return cfg_settings;
}

Now in this example you can see that we've constructed an object of the type 'Setting' now there are a few way you can construct a setting but we are going to use the following method (if you want to know more about the other way to create a Setting Object you can see the com.audium.server.voiceElement.Setting page within the CVP JavaDoc).

Setting(String realName, String displayName, String description, boolean required, boolean single, boolean substitution, int type);
This constructor is used to create a string, boolean, or textfield setting or an integer or float setting with no upper or lower bound restrictions.

Now that our Element wouldn't be complete without having a place to go once it's finished so we need to define some ExitState(s) for the Builder by adding:

public ExitState[] getExitStates() throws ElementException {
ExitState done = new ExitState("Done","Done","Command Completed.");
ExitState error = new ExitState("Error","Error","Failed to Complete Command.");
ExitState[] exitStateArray = new ExitState[] {done};
return exitStateArray;
}

We will not be using either of the following functions ( getAudioGroupDisplayOrder() getAudioGroups() ) they are required for our Element to function.

public String[] getAudioGroupDisplayOrder() {
return null;
}
public HashMap getAudioGroups() throws ElementException {
return null;
}

Now that these are setup we can get to the interesting stuff by implementing the addXmlBody() function.

protected String addXmlBody(VMain vxml, Hashtable reParameters, VoiceElementData data) throws VException, ElementException {
// Really cood stuff goes here.
}

Now as you might have put together that we are going to start working on manipulating the VXML of our element and we have to start out by constructing our VForm, our parent object and we must do this by first loading the preferences. (You must call it "start")

VPreference pref = data.getPreference();
VForm prompt_form = VForm.getNew(pref, "start");

I'm going to skip over what is actually happening here because I don't feel I can adequately describe it well but you can find out more by reading the CVP Programming Guide.
We are going to create a VoiceElementConfig object so that we can collect the parameters for our Element that set in the Builder by you.

VoiceElementConfig cfg = data.getVoiceElementConfig();
String prompt = cfg.getSettingValue("myStringData", data);

Now that we have collected the string from the builder we need to create a VBlock object within our VForm so that we can add a VAudio item to it.

VBlock prompt_block = VBlock.getNew(pref);
prompt_form.add(prompt_block);
VAudio media_item = VAudio.getNew(pref, prompt, VAudio.TTS_ONLY);
logger.debug("TTS:"+ prompt);
prompt_block.add(media_item);

To execute the VAudio we must create a VAction and then add it to the VBlock.

VAction promt_submit = VAction.getNew(pref);
promt_submit.add(getSubmitVAction(null, pref));
prompt_block.add(promt_submit);

We must then add our VForm to the VXML document and return the Exit State of 'Done'.

vxml.add(prompt_form);
String exit_state = "Done";
return exit_state;

and then we're done! I have a repo with a copy of this element availible on My Github