Skip to content

Anatomy of a Zervicepoint plugin

An Zervicepoint plugin is a collection of Zervicepoint Activities and Data sources often handling the same target system or API. Activites and data sources are building blocks for forms and workflows in a Zervicepoint service.

Plugins are can be written in PowerShell, C#, F# or VB.NET

PowerShell Plugin

Folder Structure

Example - AD Plugin

Click to show example 
Active Directory
|
└───Activities
│   │
│   └───Activity.ActiveDirectory # PowerShell Module containing activities
│       │   Activity.ActiveDirectory.psd1
│       │   Activity.ActiveDirectory.psm1
│       |
|       └───en-us
|       |   |
|       |   | Activity.ActiveDirectory.psd1 # Localized Data
|       |
|       └───sv-se
|           |
|           | Activity.ActiveDirectory.psd1 # Localized Data
│
└───Data sources
│   │
│   └───DropDown.ADComputer # PowerShell Module for a DropDown data source
│   |   │   DropDown.ADComputer.psd1
│   |   │   DropDown.ADComputer.psm1
│   |   |   dropdown.xml
|   |
|   └───DropDown.ADComputerNoDefault
│   |   │   DropDown.ADComputerNoDefault.psd1
│   |   │   DropDown.ADComputerNoDefault.psm1
│   |   |   dropdown.xml
|   |
|   └───WebService.ActiveDirectory # PowerShell module for data sources called via javascript in forms
│       │   WebService.ActiveDirectory.psd1
│       │   WebService.ActiveDirectory.psm1
|
└───Shared modules # Helper modules shared by both activities and data sources.
    |
    └───ActiveDirectory # Helper AD module
    |   |
    |   |   ActiveDirectory.psd1
    |   |   ActiveDirectory.psm1
    |
    └───DropDown.ADComputer # Generic DropDown used by DropDownADComputer and DropDown.ADComputerNoDefault
        |
        |   DropDown.ADComputer.psd1
        |   DropDown.ADComputer.psm1

Configuration

Configuration for Zervicepoint plugins usually includes the following

  • Update provider config for Client Web Service
    • C:\Program Files\Zipper\Zervicepoint\ClientWebService\pluginname.clientwebservice.providers.xml
  • Update provider config for Provisioning System
    • C:\Program Files\Zipper\Zervicepoint\provisioningsystem\pluginname.clientwebservice.providers.xml
  • Update plugin related delegation files such as dropdown.xml
  • Add secrets to Credential Store for service account running ProvisioningSystem/ClientWebService.

Configure provider config

In order for a PowerShell or .NET Provider to be imported to Zervicepoint, the provider configuration file must exist. The provider config file contains metadata for the provider, as well which provider type and scriptpath to import activites/data sources from.

Data sources are inventoried by ProvisioningSystemInventory and it imports provider config files from 'C:\Program Files\Zipper\Zervicepoint\ClientWebService\'

Activities are inventoried by ProvisioningSystem and it imports provider config files form 'C:\Program Files\Zipper\Zervicepoint\ProvisioningSystem\'

Provider Config 

<?xml version="1.0" encoding="utf-8"?>
<providers> 
<provider name="MS Active Directory"> <!--This name must be unique-->
    <assembly type="Zipper.ZervicePoint.ProvisioningSystem.PowerShellProvider.PowerShellEngine" assemblyFile="C:\Program Files\Zipper\ZervicePoint\ProvisioningSystem\Providers\PowerShell\Zipper.ZervicePoint.ProvisioningSystem.PowerShellProvider.dll" /> <!-- assembly type PowerShell/Dotnet and if data source/activity-->
    <configuration>
    <add key="scriptpath" value="C:\Program Files\Zipper\ZervicePoint\Provider extensions\Active Directory\Activities\" /> <!-- Location to look for modules to import -->
    <add key="DomainController" value="DC01.domain.local" /> <!-- custom config key/value config -->
    <add key="SearchBase" value="OU=Demo,DC=domain,DC=local" /> <!-- custom config key/value config -->
    </configuration>
</provider>
</providers>

Additional configuration key/value pairs can be added in order to be used by $config parameter.

Zervicepoint plugins may create two provider config files.

Name Path
plugin.clientwebservice.provider.xml C:\Program Files\Zipper\Zervicepoint\ClientWebService\
plugin.provisioningsystem.provider.xml C:\Program Files\Zipper\Zervicepoint\ProvisioningSystem\

Example - AD provider.xml

Click to show example 
<?xml version="1.0" encoding="utf-8"?>
<providers>
<provider name="MS Active Directory">
    <assembly type="Zipper.ZervicePoint.ProvisioningSystem.PowerShellProvider.PowerShellEngine" assemblyFile="C:\Program Files\Zipper\ZervicePoint\ProvisioningSystem\Providers\PowerShell\Zipper.ZervicePoint.ProvisioningSystem.PowerShellProvider.dll" />
    <configuration>
    <add key="scriptpath" value="C:\Program Files\Zipper\ZervicePoint\Provider extensions\Active Directory\Activities\" />
    <add key="DomainController" value="DC01.domain.local" />
    <add key="SearchBase" value="OU=Demo,DC=domain,DC=local" />
    <add key="SharedFolderProperty" value="info" />
    <add key="SharedFolderReadGroup" value="R-" />
    <add key="SharedFolderWriteGroup" value="RW-" />
    <add key="SoftwareGroupAttribute" value="ExtensionAttribute3" />
    <add key="SoftwareGroupValue" value="software" />
    <add key="UICulture" value="en-US" />
    </configuration>
</provider>
</providers>

Configure dropdown.xml

Most of our Zervicepoint plugins, includes a dropdown.xml file which is used to manage delegation or to control the search scope of a query in a data source.

Example - AD dropdown.xml

In this example the SearchBase and DomainController is different depending on the zervicepoint roles the user is member of.

Click to show example 
<?xml version="1.0" encoding="utf-8"?>
<dropdowns>
<dropdown>
    <parameter name="LDAPFilter">
    <add key="EuropeAdmins" value="(&amp;(objectCategory=computer)(anr=$search*))"/>
    <add key="NorthAmericaAdmins" value="(&amp;(objectCategory=computer)(anr=$search*))"/>
    <add key="AsiaAdmins" value="(&amp;(objectCategory=computer)(anr=$search*))"/>
    <add key="ZPITAdmins" value="(&amp;(objectCategory=computer)(anr=$search*))"/>
    </parameter>
    <parameter name="SearchBase">
    <add key="EuropeAdmins" value="OU=Users,OU=Europe,DC=Demo,DC=DC=local"/>
    <add key="NorthAmericaAdmins" value="OU=Users,OU=NorthAmerica,DC=Demo,DC=DC=local"/>
    <add key="AsiaAdmins" value="OU=Users,OU=Asia,DC=Demo,DC=DC=local"/>
    <add key="ZPITAdmins" value="$config.SearchBase"/>
    </parameter>
    <parameter name="DomainController">
    <add key="EuropeAdmins" value="eudc01.demo.local"/>
    <add key="NorthAmericaAdmins" value="nadc01.demo.local"/>
    <add key="AsiaAdmins" value="asdc01.demo.local"/>
    <add key="ZPITAdmins" value="$config.DomainController"/>
    </parameter>
    <default>
    <add key="EuropeAdmins" value="(&amp;(objectCategory=computer)(managedby=$currentUser.DistinguishedName))"/>
    <add key="NorthAmericaAdmins" value="(&amp;(objectCategory=computer)(managedby=$currentUser.DistinguishedName))"/>
    <add key="AsiaAdmins" value="(&amp;(objectCategory=computer)(managedby=$currentUser.DistinguishedName))"/>
    <add key="ZPITAdmins" value="(&amp;(objectCategory=computer)(managedby=$currentUser.DistinguishedName))"/>
    </default>
    <output>
    <add key="Id" value="ObjectGUID"/>
    <add key="Name" value="Name"/>
    </output>
</dropdown>
</dropdowns>

Tip

For more details of any customization available in a plugin, go to to the plugin documentation.

Configure Data sources

If plugin allows for data source access control through a dropdown.xml you may need to configure the dropdown.xml to reflect the roles used in your store.

Add Credentials/Secrets

Zervicepoint plugins which must use credentials/secrets in order to authenticate to an API or system must store the secrets in the Credential Store of service account running ClientWebService or ProvisioningSystem.

Credentials can be added either by running Credential Manager in the context of the service account.

Add Credential/Secret using PowerShell

start-process powershell -Credential (Get-Credential -UserName "<domain>\<username>" -Message "Enter password for clientwebservice/provisioningsystem service account")

# In the new powershell window running in the context of the service account
Import-Module "C:\Program Files\Zipper\ZervicePoint\Powershell\ZervicePoint.WebApi.PowerShell"
Set-ZPKeyCredential -Name "<CredentialName>" -UserName "<user>" -Key "<password/secret>"

Tip

New-PFCredential is a cmdlet included in PowerFrame.Security that can also be used to add credentials

Dependencies

Plugin dependencies varies depending on the plugin, but is usually packages, tools, modules or api keys generated from a 3rd party. (e.g Active Directory plugin requires Microsoft Active Directory Module)

Installation Path

  • Zervicepoint Plugins are installed on the server running the Zervicepoint roles ProvisioningSystem, ProvisioningSystemInventory and ClientWebService.
  • Installation directory is C:\Program Files\Zipper\Zervicepoint\Provider Extensions\PluginName
  • Zervicepoint plugin installer sets the System Variable ZPPackages to C:\Program Files\Zipper\Zervicepoint\Provider Extensions