Please note that this module requires at least SwyxWare 2011.

What is Windows PowerShell?

Windows PowerShell is Microsoft's successor of the old DOS command prompt. It's a command shell and scripting language based on Microsoft.Net. The name sounds exaggerated, but the shell is powerful. You have the full Microsoft.Net class library available. Filesystem, Registry, WMI, Windows Performance Counter, Windows Eventlog, databases, active directory. It's all covered. Microsoft no longer releases any Windows server product without PowerShell support.

Wikipedia has some details about the shell: http://en.wikipedia.org/wiki/Windows_PowerShell

What is a PowerShell module?

A module is an easy to install package of PowerShell commands, scripts, aliases, etc. You get a bunch of files to copy into a well-known folder on your hard disk, enter

import-module <modulename>

in your shell and you're ready to go.

Why a SwyxWare PowerShell module?

The Microsoft WSE 3.0 based ConfigDataStore API of SwyxWare v6.0 cannot be easily used in PowerShell. With SwyxWare v8.0 the CDS Client is based on Microsoft Communication Foundation instead of WSE, PowerShell got modules for easy deployment and using both together is now straight-forward.

There are several reasons for a SwyxWare PowerShell module. First it started as a spare time project of Martin, because he want to explore what’s possible with Windows PowerShell, and to check if it might be an answer to the bulk-administration features some partners and customers are missing in SwyxWare for some time. Later, Swyx needed an easy and flexible way to write smoke tests for our automatic build system for SwyxWare v8.0 and the PowerShell support had been used. Finally some test engineers started using it to automate some tests and we’re now convinced that it will indeed be a powerful administration tool for SwyxWare complementing the classic Microsoft Management Console.

Why an Open-Source Project on this website?

The SwyxWare PowerShell module will not be a part of the product. At least not in v8.0. Swyx simply has not the time to create a feature set which is ready for a production release. To get a feature into the product you need to design it, implement it, document it, localize it, test it and finally train your support staff. That's just not possible for v8.0, sorry.

PowerShell is rather new for Swyx. There are some guidelines from Microsoft on how to design cmdlets, what are the most important do’s and don’ts. But Swyx do not feel to have enough experience to design a good enough set of cmdlets to keep it for a long time. If Swyx adds a set of cmdlets to the product it cannot be changed in the next version, without breaking existing scripts you might have written in the meantime. As a product feature it would be much more “fixed” than it should be at this stage.

The SwyxWare PowerShell module is completely written as PowerShell scripts. Just fire up a text editor of your choice, open the ps1-files and have a look. It's fully based on the ConfigDataStore API, SwyxWare's official configuration API. So it's open anyway. Everybody could change or extend it. Therefore hosting it as a project here is an ideal way to let the whole Swyx community benefit by sharing your scripts and extensions. It lets the community and and Swyx itself gain experience and allows us to change and complete it as we see fit without the restrictions of a tight product release schedule.

What can I do with it?

Theoretically you're able to configure everything what's is possible to configure with SwyxWare Administration. In practice you need to have PowerShell commands, called Cmdlets to make it easy to use the CDS API inside the shell. While it's possible to use the whole CDS API inside PowerShell, it's not that easy, because CDS API had been designed with a software developer in mind, not an administrator.

Here are some tasks you could do with the module and some Windows PowerShell know-how:

• You can retrieve user objects, filter, sort, list them, make changes. You can create users, set there properties, delete them, add or remove them to/from groups.
• You can create, edit or delete trunks, trunk groups, routing records
• Import or update SwyxWare users from another data source like a database, csv file, active directory.
• Logoff users
• Retrieve or set standard redirections
• Retrieve or set users rich presence status or status text
• Retrieve or set users settings (e.g. speed dial keys)
• Because CDS API can be used via a network you can run PowerShell on a separate system and manage one or more SwyxWare instances.

There are probably a lot more we just cannot imagine right now.
 

What do I need to use it?

• Windows PowerShell 2.0
• SwyxWare v8.0
• SwyxWare Administration v8.0 or SwyxIt! v8.0 installed on the system where you're using the module.
• Some experience with Windows PowerShell is an advantage
• Some knowledge about writing scripts probably helps as well.
   

Where can I get support?

As long as it's an open-source project on this website, i.e. the Swyx community is your support team. This means the projects forum is the place for your support requests. However, Swyx development and QA is using it, too, and will increase it's usage in the future. Expect some Swyx software and test engineers to participating here. Sebastian the project lead for the PowerShell module on this Website is a Swyx software developer, too.

Conclusion

Windows PowerShell is one the best products Microsoft released in the last couple of years. Supporting it in SwyxWare will eventually make administrator’s life much, much easier. Swyx will use and extend it internally and will contribute to the project.

The forums of this project will be used to gather the scripts over the time, as well as this page.

Software Requirements:

• Windows PowerShell 2.0

Compatible Operating Systems:

• Windows XP
• Windows Server 2003
• Windows Vista
• Windows Server 2008
• Windows 7
• Windows Server 2008 R2

This is how to setup the IpPbx Powershell Module:

1. Download and start the setup package.
    
2. If you've never used Powershell scripts before, start the shell with administative rights and enter the following command to enable script execution
   
   Set-executionpolicy –scope localmachine remotesigned
   
   If you want to execute unsigned scripts stored on a network location you must use the following command instead (NOT RECOMMENDED!):
   
   Set-executionpolicy unrestricted
    
3. Select the "Install.ps1" file from the setup package, open the context menu and choose "Run with Powershell". Now follow the instructions of the installation script.
   
   If the "Run with Powershell" context menu does not exist do the follwing:
   
   Copy subfolders IpPbx and Accelerators into your Windows Powershell module folder, usually located at
   
   <my documents>\WindowsPowershell\Modules
   
   If you want to install the module for "All Users" copy both folders into the following directories:
   
   %windir%\System32\WindowsPowerShell\v1.0\Modules
%windir%\SysWOW64\WindowsPowerShell\v1.0\Modules
    
4. Check your module installation
    
   To verify that the module is available, enter the following command:
   
   Get-Module -ListAvailable
   
   The result list must contains the following entries:
   
   Script     Accelerators
Manifest   IpPbx


The following describes the usage of the IpPbx Powershell Module:

1. Enter the following command to import the IpPbx Powershell Module:
   
   Import-Module IpPbx
   
   If you want to check that the module was loaded successfully enter the following:
   
   Get-Module
   
   The result list must contain the following entry: 
   
   Manifest   IpPbx
   
    
2. Get module help:
   
   Get-help IpPbx

This is a Swyx Forum project. All support, enhancement and bug requests must be placed into the project's forums.

No other support is available!

Use the Using IpPbx Powershell Module forum for all usage related topics, use the Development forum for all development, enhancement related topics.

IpPbx Powershell Module

This is a Swyx Forum Open Source Project.

This software is licensed under the MIT license (see below).

Copyright (c) 2011-2012 by Swyx Forum
Copyright (c) 2011-2012 by Martin Hüser and Sebastian Dreier

This software makes use of the following third party components:

Custom Accelerators for PowerShell 2 by Joel Bennett
http://poshcode.org/1398

Export-PSCredential by Hal Rottenberg
http://halr9000.com
 

Massachusetts Institute of Technology (MIT) License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.