Create K2 Packages using PowerShell

Once you have created a package as per step 1 of the Quick steps, follow the steps below to add the PowerShell snap-in and generate the configuration file.

1. Open Microsoft PowerShell with administrator privileges.

   When copying code from this Help file to the PowerShell interface, make sure there aren't any extra line breaks in the code text.

2. Enter the PowerShell environment setup command to add the PowerShell snap-in. You use this command for every package creation:
   Copy

   Adds the PowerShell Deployment snapin

   1
   Add-PSSnapin SourceCode.Deployment.Powershell

3. Enter the Write-PackageConfig command to create a configuration file that you will use to customize the artifact settings for creating the package. This command takes two arguments: the package file, and the XML file. It examines the package and creates the configuration file with default values for all artifacts. This *.XML file is what you edit to specify what you want to package, then use the New-Package command to create the package. An example of this command is as follows:
   Copy

   Scripts the sample XML configuration file to be used for package creation

   1
   Write-PackageConfig C:\Powershell\MyPackage.kspx C:\Powershell\MyPackage.xml

Customize the Write-PackageConfig command with the following options:

• -InputFile (where 'InputFile' is the *.KSPX (K2 package) file you created.)

• -OutputFile (where 'OutputFile' is the corresponding *.XML configuration file that will be generated.)

• An optional command is -ConnectionString (connection string to K2 server, for example: “Host=LOCALHOST;Port=5555;Integrated=True;IsPrimaryLogin=True”. Defaults are used if not specified)


Example of a generated configuration file

Edit the contents of the configuration *.XML file to customize the artifact settings, using the parameters below:

Parameter (<p/>)

This parameter validates the contents of the package.

• <p validate="true"> - Validates package items on creation when this parameter is set to “true”. If any validation errors are detected, an error log file is produced in the same location as the package. If this parameter is set to "false", no validation occurs when the package is created.
  Copy

  Validate package example

  1
  2
  3
  <?xml version="1.0" encoding="utf-8"?>
                                          <c xmlns="http://schemas.k2.com/Package">
                              <p validate="true" >   

• <p cat=“Category name"> - If you want to specify a category to be packaged, the cat parameter can be used, for example <p cat="Hello World Solution". The entire contents of the category (including dependencies) is packaged.
  When you specify a category name, the first category that matches that name is used in the package. If the category that you want to package has the same name as another but is nested, you can specify a path in the argument for example cat=“root/Sales/MyLeave”
  Copy

  Example with category specified

  1
  2
  3
  <?xml version="1.0" encoding="utf-8"?>
                                          <c xmlns="http://schemas.k2.com/Package">
                      <p cat="Hello World Solution" validate="true" >  

Exclude (<exs/>)

This parameter excludes a specific type from the package, such as SmartObjects, views, or forms. For example, you want to package an entire category, except for the workflows. If you exclude the type "Workflow", all workflows in that category will be excluded.

• n – the type name of the item
• ns - the basenamespace of the item

Examples of type names and basenamespaces

• n=“SmartObject” ns=“urn:SourceCode/SmartObjects”
• n=“View” ns=“urn:SourceCode/SmartForms”
• n=“Form” ns=“urn:SourceCode/SmartForms”
• n=“Workflow” ns=@“urn:SourceCode/Workflow”

Copy

Example of using exclude parameter to exclude all forms from the package

1
2
3
4
5
6
<?xml version="1.0" encoding="utf-8"?>
                                <c xmlns="http://schemas.k2.com/Package">
                                <p validate="true" >
                                <exs>
                                <e n="Form" ns="urn:SourceCode/SmartForms">
                    </exs>

Include (<incs/>)

The <i /> parameter specifies what to include in the package line items.

• n - the name of the item

• ns - the namespace of the item

• includeDependencies – by specifying either "true" or "false", dependencies of that line item are included or excluded when packaging



Copy

Example of using include parameter

1
2
3
4
5
<incs>      
                                    <i n="Validation View" ns="urn:SourceCode/SmartForms/View" includeDependencies="true" />
                                    <i n="ValidSmO" ns="urn:SourceCode/SmartObjects/SmartObject" includeDependencies="true" />
                                    <i n="ValidSmO" ns="urn:SourceCode/SmartObjects/SmartObjectData?ValidSmO" includeDependencies="true" />      
                    </incs>

Remove (<rem/>)

The <r /> parameter defines a specific line item to remove from the package. For example you want to package your solution but leave out a specific SmartObject. Use the <r /> parameter to specify the SmartObject you want to remove from the solution before packaging.

• n - the name of the item
• ns - the namespace of the item
• includeDependencies – by specifying either "true" or "false", dependencies of that line item are included or excluded when removing the item from packaging

Examples of type names and basenamespaces

• n=“SmartObject” ns=“urn:SourceCode/SmartObjects/SmartObject”
• n=“View” ns=“urn:SourceCode/SmartForms/View”
• n=“Form” ns=“urn:SourceCode/SmartForms/Form”
• n=“Workflow” ns=“urn:SourceCode/Workflows”

Copy

Example of using remove parameter

1
2
3
 <rem>
                                <r n="StandaloneSmartObject" ns="urn:SourceCode/SmartObjects/SmartObject" includeDependencies="true" />
                    </rem>

Variables (<vars/>)

Use the <v /> or <vr /> parameter to include variables in the package.

• n - the name of the item

• ns - the namespace of the item. “urn:SourceCode/ModelVariables”

• desc – description (optional)

• type - variable type

• value - value of variable



Copy

Example of using the variable parameter

1
2
3
4
5
6
7
8
9
10
11
12
13
<vars>
                                    <v n="FromAddressEmail" ns="urn:SourceCode/ModelVariables" desc="Descroption for Variable Email Add" type="String" value="k2service@denallix.com">
                                    <vr n="FieldValue" ns="urn:SourceCode/EnvironmentSettings/Fields?From Address" />
                                    </v>
                                    <v n="DateTimeVar" ns="urn:SourceCode/ModelVariables" desc="" type="DateTime" value="1/1/0001 12:00:00 AM">
                                    <vr n="DateTimeVar" ns="urn:SourceCode/Workflows?Vars\vars Workflow#DataField" />
                                    </v>
                                    <v n="IntVar" ns="urn:SourceCode/ModelVariables" desc="" type="Int32" value="2">
                                    <vr n="IntVar" ns="urn:SourceCode/Workflows?Vars\vars Workflow#DataField" />
                                    </v>
                                    <v n="TextVar" ns="urn:SourceCode/ModelVariables" desc="" type="String" value="Bloop">
                                    <vr n="TextVar" ns="urn:SourceCode/Workflows?Vars\vars Workflow#DataField" />
                    </vars>

Once you have created and edited the package configuration file, use the New-Package command to create the package. Customize the New-Package command with the following options:

• -FileName (Required) The full name and file extension of the package *.kspx file to be created.
• -ConfigFile (Optional) If an *.XML configuration file with the same name as the package file is found in the same folder, it is used. If you have stored the *.XML configuration file in another location, specify the full path.
• -ConnectionString (Optional) The connection string to the K2 server, for example: “Host=LOCALHOST;Port=5555;Integrated=True;IsPrimaryLogin=True”. Defaults are used if not specified

• -K2Host Specify the K2 server name. LOCALHOST is the default
• -Port The port through which package and deployment connects to the K2 server. S5555 is the default
• -Integrated (Optional) Specify whether the connection is integrated or not. True is the default and uses credentials of the person executing the command
• -IsPrimaryLogin (Optional) True is the default
• -UserName (Required if Integratedis set to 'False') The username used for connecting to the K2 server
• -Password (Required if Integrated is set to 'False') The password used for connecting to the K2 server
• -WindowsDomain (Required if Integrated is set to 'False') The domain associated with the UserName
• -SecurityLabel (Required if Integratedis set to 'False') For example, 'K2'

A sample New-Package command is as follows:

1
New-Package C:\Powershell\MyPowerShellPackage.kspx C:\Powershell\MyPackage.xml -OutputLog true

By default, the output log file is saved to the same location as the package file you used for the creation.

You specify service instances using the namespace and class structure, while all other artifacts use the namespace and name structure. All structures must be unique.

For example, the SQL Server Service is specified in the configuration file as shown below. Note that %2E is used to denote a full stop/period character:

1
SourceCode%2ESmartObjects%2EServices%2ESQL%2EsqlServerService

The namespace structure used for Package and Deployment directly relates to the namespace and class within the assembly, which inherits properties from ServiceAssemblyBase. For the SQL Server Service example, the name of the assembly is SourceCode.SmartObjects.Services.SqlServer.dll. However, the namespace and class structure is as follows:

1
2
3
4
5
6
7
8
9
namespace

                SourceCode.SmartObjects.Services.SQL

                {

                public class SqlServerService : ServiceAssemblyBase

            {

More examples