Cisco Unified Communication Tools

REST .NET SDK

Version   3.0.10 
Last Update   4/27/2013
Statistics   Requires Visual Studio 2010 or 2012 and the .NET 4.0 framework and a Connection server capable of serving up CUPI, CUMI and CUTI functionality.  The library was built against Connection 9.1, however most functions will work for older versions as well. 
Compatibility   Unity Connection 8.5.1 or later for all functionality.  8.6 or later is reccomended
Support   NOT TAC supported - support is through the developer forus, the links page has details.

The REST .NET SDK wraps much of the administrator API (CUPI) interface, much of the CUMI (for messages) and CUTI (for using the phone as a recording device) is also included.  If you're looking for a wrapper for leveraging end user access (i.e. users authenticating as themselves accessing information about their own accounts) you may be interested in the CUPI for Users .NET library instead.

NOTE: NuGet package management for the REST SDK is coming soon!  Stay tuned...

Training videos:

Getting started with the ConnectionCUPIFunctions class library:  Adding the library to your project, attaching to Connection, getting version information, finding a user, listing various user properties. CUPI .NET library intro - 17 mintes - MP4 web video plays in web browser
Basic adds/changes/deletes: Add a new user, updating properties on the user, delete them in a few different ways. CUPI CRUD with .NET Library - 26 minutes
Using Fiddler for viewing HTTP traffic: Quick intro to using Fiddler to watch HTTP/S traffice going into and out of your development platform so you can see what's happening with the various Connection REST interfaces. Using Fiddler - 6 minutes

The library itself can be fetched using a SubVersion client pointed to the public repository here:

https://xp-dev.com/svn/ConnectionRestSdk

This is a read only public repository - there is no login or password necessary to download it.  The repository includes both the ConnectionCUPIFunctions library itself as well as a small Windows forms application used as a test harness called CUPIFastStart that you can use to explore the capabilities of the library as well as an even smaller test library called CUPIVerySimple which is a bare bones CLI application that also uses the CUPIFunctions library.

Developers Guide

this will get expanded with many more code samples and library explanation as the project moves forward.

HTML Version

PDF Version (this is nicer to use given the bookmarks can be used for content navigation more easily)

Usage Samples

The following are some highlights of the types of things you can do with the CUPI wrapper library - the project code has more extensive examples in the CLI sample program and the unit tests included with it.

NOTE: Error handling and logging have been stripped out of these examples to keep the code clear and simple.  Copy and paste these into a production application at your peril!

Logging into Connection

 oServer = new ConnectionServer("192.168.0.198", "jlindborg", "ecsbulab");
Console.WriteLine("Logged into: " + oServer.ToString());
if (oServer.Version.IsVersionAtLeast(8,6,2,0)==false)
{
    Console.WriteLine("Version of Connection={0} and 8.6.2 or later is required",oServer.Version);
}

Getting User Info

  WebCallResult res;

UserBase oUser;
res = UserBase.GetUser(out oUser, oServer,"" , "testuser");

if (res.Success==false)
{
    Console.WriteLine("Error fetching testuser:"+res.ToString());
}

//dumps out the user alias, display name and primary extension
Console.WriteLine(oUser.ToString());

//dumps out all properties on the user object
Console.WriteLine(oUser.DumpAllProps());

Resetting User Pin

oUser.ResetPin("112233");

Getting Schedule Details

ScheduleState oState;

oState = oUser.PrimaryCallHandler().GetScheduleSet().GetScheduleState(DateTime.Now);

//will output "ACTIVE", "INACTIVE" or "HOLIDAY" depending on what the schedule details the user is assigned

Console.Writeline("Current schedule state for user="+oState.ToString());

//will output all the schedule detail items for all schedules (both regular and holiday) that the user is associated with.

 foreach (Schedule oSchedule in oUser.PrimaryCallHandler().GetScheduleSet().Schedules())
{
    Console.WriteLine("Schedule Name="+oSchedule.DisplayName);
    foreach (ScheduleDetail oDetail in oSchedule.ScheduleDetails())
    {
        Console.WriteLine("Details in schedule:");
        Console.WriteLine(oDetail.DumpAllProps("    "));
    }
}

Showing All Alternate Extensions For User

 List<AlternateExtension> oAlternateExtensions;

oAlternateExtensions = oUser.AlternateExtensions()


//output all alternate extensions - what's returned will depend on the user's COS
//settings - admin added alternate extensions may or may not be included.
    foreach (AlternateExtension oTempExt in oAlternateExtensions)
    {
        Console.WriteLine(oTempExt.ToString());
    }

Adding and Removing an Alternate Extension

 //Adding an alternate extension can be restricted by the user's class of service so expect that this
//call can fail.
AlternateExtension oAltExt;
res = AlternateExtension.AddAlternateExtension(_connectionServer, oUser.ObjectId, 3, "1234",out oAltExt);

if (res.Success)
{
    Console.WriteLine(oAltExt.DumpAllProps());

    //delete the alternate extension you just added.
    res = oAltExt.Delete();
}

Showing Greetings

 //get all greetings for a user - this should always get all 7 greetings
List<Greeting> oGreetings;
oGreetings = oUser.PrimaryCallHandler().GetGreetings();

foreach (Greeting oTempGreeting in oGreetings)
{
    //outputs the greeting type, if its enabled and what it's set to play
    Console.WriteLine(oTempGreeting.ToString());
}

Enabling and Disabling a Greeting

 //get just the alternate greeting using the static method off the Greetings class instead
Greeting oGreeting;
res = Greeting.GetGreeting(oServer, oUser.PrimaryCallHandler().ObjectId, GreetingTypes.Alternate.ToString(), out oGreeting);

//this is how you would update the enabled status of the greeting. This enables the
//alternate greeting for 24 hours
res=oGreeting.UpdateGreetingEnabledStatus(true, DateTime.Now.AddDays(1));

//This disables the greeting. If you try this on the standard or error greetings it will
//fail since disabling those greetings is illegal
res = oGreeting.UpdateGreetingEnabledStatus(false);

Getting Greeting Stream Files from a Greeting

 //get just the alternate greeting
Greeting oGreeting;
res = Greeting.GetGreeting(oServer, oUser.PrimaryCallHandler().ObjectId, GreetingTypes.Alternate.ToString(), out oGreeting);

//get the greeting streams defined for the alternate greeting
List<GreetingStreamFile> oStreamFiles;
oStreamFiles = oGreeting.GetGreetingStreamFiles();

//if there are no custom recordings in any language for this greeting the stream files returned
//will be null
if (oStreamFiles != null)
{
    Console.WriteLine(oStreamFiles.Count.ToString());

    //for each language wav file found for the greeting, save it off as a uniquely
    //names wav file using a new GUID
    foreach (GreetingStreamFile oStream in oStreamFiles)
    {
        res=oStream.GetGreetingWAVFile(string.Format(@"c:\tempfolder\{0}.wav", Guid.NewGuid()));
    }
}

Updating a Greeting for a User from a Local WAV File

 //get just the alternate greeting
Greeting oGreeting;
res = Greeting.GetGreeting(oServer, oUser.PrimaryCallHandler().ObjectId, GreetingTypes.Alternate.ToString(), out oGreeting);

//you can pass the language code directly as 1033 (for US English) or you can use the
//LanguageCodes class and cast it to an int to make your code a little more readable
res=oGreeting.SetGreetingWavFile((int) LanguageCodes.EnglishUnitedStates, @"c:\MyNewGreeting.wav");

Using the Phone to Record a Greeting

 //use telephone as media device - establish a connection to extension 1003
PhoneRecording oPhone;
oPhone = new PhoneRecording(oServer,"1003");

//record a new stream
res = oPhone.RecordStreamFile();

//play the stream we just recorded for confirmation
res=oPhone.PlayStreamFile();

//get just the off hours greeting
Greeting oOffHoursGreeting;
res = Greeting.GetGreeting(oServer, oUser.PrimaryCallHandler().ObjectId, GreetingTypes.OffHours.ToString(), out oOffHoursGreeting);

//set it's US English recording to the recording we just made
res=oOffHoursGreeting.SetGreetingRecordingToStreamFile((int)LanguageCodes.EnglishUnitedStates,
                oPhone.RecordingResourceId);

Showing Transfer Options

 //get all the user's transfer option
List<TransferOption> oTransferOptions;
oTransferOptions = oUser.PrimaryCallHandler().GetTransferOptions();

foreach (TransferOption oTempOption in oTransferOptions)
{
    //outputs the transfer type, if its enabled and what it's action is
    Console.WriteLine(oTempOption.ToString());
}

Editing Transfer Options

 //get just the alternate transfer option
TransferOption oAltOption;
res = TransferOption.GetTransferOption(oServer, oUser.PrimaryCallHandler().ObjectId, TransferOptionTypes.Alternate.ToString(), out oAltOption);

//update the transfer option to be enabled indefinitely.
oAltOption.UpdateTransferOptionEnabledStatus(true);

//set the transfer option to ring the phone for x1234 5 times and not play the "please wait while
//I transfer your call" prompt.
oAltOption.Extension = "1234";
oAltOption.PlayTransferPrompt = false;
oAltOption.TransferRings = 5;
oAltOption.Action = (int)TransferActionTypes.Transfer;

//apply the changes to the option
res = oAltOption.Update();