Skip to content

Getting started

With ZervicePoint PowerShell Management

Introduction to PowerShell Management

Zervicepoint PowerShell Management is a PowerShell module that contains CmdLets that you can use in order to interact with a Zervicepoint store to perform various management or administration tasks.

Use Get-Help for example scripts

The most up-to-date documentation for all Zervicepoint PowerShell Management commands is available in the help files. Use Get-Help for generic help, get examples or the get the full command documentation:

Get-Help <cmdlet>

Get-Help <cmdlet> -Examples

Get-Help <cmdlet> -Full

Get a list of all available Zervicepoint PowerShell Management commands:

Get-Command *-ZP*

Overview

In the following video you can learn about some of the different cmdlets in the Zervicepoint PowerShell API

Environment Variables

The following environment variables may be set in order to simplify use of the powershell cmdlets:

ZPAPIURL
If this variable is set, you can omit the -Url parameter from all cmdlets
ZPAPIADFSHOST
If this variable is set, you can omit the -AdfsServerHost parameter from the Get-ZPSecurityToken cmdlet
ZPAPIAUDIENCEURI
If this variable is set, you can omit the -AudienceUri parameter from the Get-ZPSecurityToken cmdlet

Machine Environment Variables

[system.environment]::SetEnvironmentVariable('ZPAPIURL', 'https://whiteowl.rig51.local:30000/Store', [System.EnvironmentVariableTarget]::Machine)
[system.environment]::SetEnvironmentVariable('ZPAPIADFSHost', 'auth.rig51.local', [System.EnvironmentVariableTarget]::Machine)
[system.environment]::SetEnvironmentVariable('ZPAPIAudienceUri', 'https://whiteowl.rig51.local', [System.EnvironmentVariableTarget]::Machine)

Importing the module

Import-Module "C:\Program Files\Zipper\ZervicePoint\Powershell\ZervicePoint.WebApi.PowerShell"

Authentication and access control

When authenticating towards the Zervicepoint PowerShell API you currently have two options. Either use ADFS or a Key. ADFS requires the ADFS service running in your environment which provides tokens to prove your identity. Using a key does not require any additional services as the key itself proves your identity.

In order to use any of the API controller methods, the user must be a member of the ApiStoreAdministrator role. The user's Email claim must also be populated.

Acquiring and setting a key

Please read Setting up Zervicepoint PowerShell management to work with key

Acquiring and setting a security token

Before you can use any of the PowerShell Cmdlets, you need to acquire a security token from an ADFS server. This is achieved by calling the Get-ZPSecurityToken cmdlet specifying the ADFS server hostname, the audience URI and an optional credentials object. In the example below, a security token is acquired from the ADFS server specified in the ZPAPIADFSHOST environment variable. The token issued is valid for the audience URI specified in the ZPAPIAUDIENCEURI environment variable and the user specified in the credential object. The Set-ZPSecurityToken cmdlet then sets the token to be used in subsequent cmdlets whenever the -SecurityToken parameter is not supplied.

$cred = Get-Credential
$token = Get-ZPSecurityToken -Credential $cred
Set-ZPSecurityToken -SecurityToken $token

What you can do with Zervicepoint PowerShell Management

Currently, the following operations are supported:

  • Services and Processes
    • Getting existing services and processes (all or by unique Id)
    • Converting services and processes to JSON strings for intermediate storage
    • Converting JSON strings to services and process objects
    • Creating new services and processes (from objects or from scratch)
    • Updating existing services and processes
    • Removing existing services and processes
  • User profiles
    • Getting existing user profiles (by Id or Email address)
    • Creating new user profiles
    • Updating existing user profiles
    • Removing existing user profiles
  • Tasks
    • Getting existing tasks (by unique Id, order id or assignee)
    • Updating task status (approve/reject and manual task status)
  • Delegations
    • Getting existing delegations (by unique Id, delegator or delgatee)
  • Media
    • Getting existing media from the database
    • Uploading new media
  • Cart files (Blobs)
    • Getting files uploaded by the user when a service is ordered
  • Categories
    • Getting existing categories (all or by unique Id)
    • Converting categories to JSON strings for intermediate storage
    • Converting JSON strings to category objects
    • Creating new categories
    • Updating existing categories
    • Removing existing categories
    • Moving and reordering categories
  • Email templates
    • Getting existing templates (all, by unique Id or by name)
    • Converting templates to JSON strings for intermediate storage
    • Converting JSON strings to template objects
    • Creating new templates
    • Updating existing templates
    • Removing existing templates
  • Orders
    • Generating new orders
    • Getting existing orders (with filtering capabilities)

Examples

How to export and import services with ZervicePoint PowerShell Management
How to make a copy of a service with ZervicePoint PowerShell Management
How to place an order with ZervicePoint PowerShell Management

Examples of individual cmdlet usage are also included in the help files:

Get-Help <cmdlet> -Examples

CmdLets and syntax

You can obtain information about the cmdlets and syntax by using the Get-Help cmdlet, providing the name of the cmdlet and the optional parameters -Detailed or -Full.

Use Get-Command for a complete list of all cmdlets:

Get-Command -Module ZervicePoint.WebApi.PowerShell

Use Get-Help cmdlet for information about a specific cmdlet:

Get-Help Get-ZPService -Full

This will give you the following result:

NAME
    Get-ZPService

SYNOPSIS
    Gets an existing service from the store


SYNTAX
    Get-ZPService [-Url <string>] [-SecurityToken <GenericXmlSecurityToken>] [-Key <string>] [-KeyCredential
    <CredentialManagement.Credential>] [-KeyCredentialName <string>] [-RequestTimeOut <int or TimeSpan>] [-RetryCount
    <int>] [-RetryDelay <int>] [-RetryStatusCode <List<int>>] [<CommonParameters>]

    Get-ZPService -UniqueId <Guid> [-Url <string>] [-SecurityToken <GenericXmlSecurityToken>] [-Key <string>]
    [-KeyCredential <CredentialManagement.Credential>] [-KeyCredentialName <string>] [-RequestTimeOut <int or
    TimeSpan>] [-RetryCount <int>] [-RetryDelay <int>] [-RetryStatusCode <List<int>>] [<CommonParameters>]

    Get-ZPService -Id <int> [-Url <string>] [-SecurityToken <GenericXmlSecurityToken>] [-Key <string>] [-KeyCredential
    <CredentialManagement.Credential>] [-KeyCredentialName <string>] [-RequestTimeOut <int or TimeSpan>] [-RetryCount
    <int>] [-RetryDelay <int>] [-RetryStatusCode <List<int>>] [<CommonParameters>]


DESCRIPTION
    The Get-ZPService cmdlet gets existing services from the store.


PARAMETERS
    -UniqueId <Guid>
        Specifies the unique Id of the service to get.

        Required?                    true
        Position?                    named
        Default value
        Accept pipeline input?       true
        Accept wildcard characters?  false

    -Id <int>
        Specifies the id of the service to get.

        Required?                    true
        Position?                    named
        Default value
        Accept pipeline input?       true
        Accept wildcard characters?  false

    -Url <string>
        Specifies the url to the store in the web api site ie "https://<zervicepointurl>:30000/<storename>/".

        The -Url parameter can be omitted if you set the url in the ZPAPIURL environment variable before calling the
        cmdlet.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -SecurityToken <string>
        Specifies the security token to use for authorization when authentication method is ADFS.

        If this parameter is omitted, the last used security token will be reused.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -Key <string>
        Specifies the access key to use for authorization when authentication method is KEY.

        If neither Key, KeyCredential nor KeyCredentialName are specified, the command will look for a credential with
        the same name as the API URL.

        To create a key credential, use the Set-ZPKeyCredential cmdlet specifying the key supplied by an
        administrator, and the API URL.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -KeyCredential <CredentialManagement.Credential>
        Specifies a credential containing the access key to use for authorization when authentication method is KEY.

        If neither Key, KeyCredential nor KeyCredentialName are specified, the command will look for a credential with
        the same name as the API URL.

        To create a key credential, use the Set-ZPKeyCredential cmdlet specifying the key supplied by an
        administrator, and the API URL.

        To retieve the credential for this parameter, use the Get-ZPKeyCredential cmdlet.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -KeyCredentialName <string>
        Specifies the name of a credential containing the access key to use for authorization when authentication
        method is KEY.

        If neither Key, KeyCredential nor KeyCredentialName are specified, the command will look for a credential with
        the same name as the API URL.

        To create a key credential, use the Set-ZPKeyCredential cmdlet specifying the key supplied by an
        administrator, and the API URL.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -RequestTimeOut <int or TimeSpan>
        Specifies the number of seconds before the request times out.

        Can be either an integer specifying the number of seconds, or a TimeSpan variable created by the New-TimeSpan
        cmdlet.

        Required?                    false
        Position?                    named
        Default value                100
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -RetryCount <int>
        Specifies the number of times to retry when a request fails.

        Required?                    false
        Position?                    named
        Default value                0
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -RetryDelay <int>
        Specifies the delay (in milliseconds) between retries.

        Required?                    false
        Position?                    named
        Default value                500
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -RetryStatusCode <List<int>>
        Specifies a list of http status codes that will trigger a retry.

        Required?                    false
        Position?                    named
        Default value                400,408,409,500,503,504
        Accept pipeline input?       false
        Accept wildcard characters?  false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).

INPUTS

OUTPUTS
    Zipper.ZervicePoint.WebApi.PowerShell.Models.Service
        The Service class represents a service in the ZervicePoint store.


    ----------  EXAMPLE 1  ----------

    PS C:\>Get-ZPService

    This example gets all services from the store.

    ----------  EXAMPLE 2  ----------

    PS C:\>Get-ZPService -UniqueId d2cc25a5-adba-4c65-aea5-0a6176698368

    This example gets the service with unique Id d2cc25a5-adba-4c65-aea5-0a6176698368 from the store.

    ----------  EXAMPLE 3  ----------

    PS C:\>Get-ZPService -Id 31

    This example gets the service with id 31 from the store.


RELATED LINKS
    New-ZPService
    Set-ZPService
    Remove-ZPService