Xapity PowerShell Activity Administration Guide www.xapity.com Document Version 1.0 August 2016
This document contains information that may change without notice. While every effort has been made to ensure that the information contained in this document is correct and up-todate, Xapity accepts no responsibility or liability to any party for any loss, damage, or disruption caused by errors, omissions, completeness or suitability of the information. This document can be used for internal and reference purposes. You cannot republish or commercially exploit the document. Nor can you store it on any other website or other form of electronic retrieval system without the written approval of Xapity. 2016 XAPTY PTY LTD. All Rights Reserved. 2
Xapity PowerShell Activity Administration Guide v1.0 Contents 1 Overview... 5 2 Supported Work Items... 5 3 License Keys... 6 4 Installation and Configuration of Xapity PowerShell Activity... 7 4.1 Install Management Pack and dll... 7 4.2 Import Management Pack... 7 4.3 Copy workflow dll to install folder... 7 5 PowerShell Activity Settings... 8 5.1 PowerShell Script Repository... 8 5.2 Creating a Script... 8 5.3 PowerShell Activity Variables... 9 5.4 PowerShell Activity Templates... 9 5.5 PowerShell Activity... 10 5.6 PowerShell Activity Error Handling... 11 6 Language Support and Overrides... 12 6.1 Edit Translation... 12 6.2 Override String Values... 14 7 Further Information... 15 7.1 Xapity Support... 15 3
4
1 Overview The Xapity PowerShell Activity enables PowerShell scripts to be run directly in any Microsoft System Center Service Manager (SCSM) workflow. With Xapity PowerShell Activity, PowerShell scripts are stored and updated centrally, script execution output can be viewed and if a script error occurs, an Email Notification can be sent. 2 Supported Work Items Xapity PowerShell Activity is supported on the following Work Items Service Request Change Request Release Record 5
3 License Keys A unique License Key is required for each SCSM Management Group. A License Key will be valid for the purchased major release version and any minor changes to that version. Minor changes will include bug fixes and minor incremental updates to functionality. A new License Key will be required when a new major version is released. Major versions will include significant changes or enhancements, new functionality or support for major changes in Service Manager. If you have a valid Support and Software Assurance Agreement, you are entitled to new License Keys for new major versions. With any purchase of a Xapity product for Service Manager, you are entitled to license two nonproduction SCMS Management Groups for your development and testing purposes. Requests for Licenses Keys for new major versions or for your nonproduction instances can be made from the Manage Keys page on the Xapity website, or by contacting Xapity. Xapity products will function for 30 days from the install date without a License Key. 6
4 Installation and Configuration of Xapity PowerShell Activity 4.1 Install Management Pack and dll Installation of Xapity PowerShell Activity involves importing a management pack and copying one workflow dll file into the Service Manager install folder. 4.2 Import Management Pack In the Service Manager console navigate to Administration\Management Packs and import the following: Xapity.PowerShellActivity.Library.mpb (change to mpb file type in import window) A restart of the console after importing a Management Pack is always recommended. Figure 1: Import Management Pack bundle 4.3 Copy workflow dll to install folder On the Service Manger workflow server copy the Xapity.PowerShellActivity.Workflows.dll to the Service Manager install folder on the workflow server - default location is C:\Program Files\Microsoft System Center 2012 R2\Service Manager (it may be different on your server if install defaults were not used): Xapity. PowerShellActivity.Workflows.dll Restart the Microsoft Monitoring Agent service Important: The dll requires a restart on the Microsoft Monitoring Agent. This will not affect analysts directly, but will pause workflows while restarting. 7
5 PowerShell Activity Settings 5.1 PowerShell Script Repository The Xapity PowerShell Activity scripts are created and stored under the Library section of Service Manager: Figure 2: Scripts Library 5.2 Creating a Script Only SCSM Administrators have permission to create scripts. Creating a new script involves giving it a title and usually copy/paste in the script. The script highlight colours are there to make it easier to read and should not be relied on to verify the code entered. Figure 3: Create a PowerShell Script 8
Script Enabled for Automation checkbox will allow you to enable or disable the script. This will allow you to create a script in draft form, and then enable it for production use when ready. Only enabled scripts can be added to the PowerShell Activity. Note: If the script has been used in a PowerShell Activity and the checkbox is cleared (disabled), then the script will not execute in any workflow and the PowerShell Activity will go into a Failed state. 5.3 PowerShell Activity Variables The PowerShell Activity includes the following variables that can be used in scripts: ActivityID the PowerShell Activity ID eg AC440 ActivityGUID the PowerShell Activity GUID eg 32737e7b-4e59-2d42-ddf1-0c7be6477a3d ParentID the ID from the parent Change, Release or Service Release eg SR567 ParentGUID the GUID from the parent Change, Release or Service Release eg cb88eebd-b027-d377-ea17-097174834b28 Using these variables allows you to write targeted scripts that can interact directly with the activity itself or the parent workflow item. Other activities or SCSM objects can be derived from these. 5.4 PowerShell Activity Templates The Default PowerShell Activity template will be blank and allows you to add a PowerShell Activity to a workflow and then configure it. You can also create additional templates with the details already filled in. Add templates for repeatable tasks and to pre-populate the base information. Figure 4: PowerShell Activity Template 9
5.5 PowerShell Activity The PowerShell Activity creates a link to a PowerShell script in the Library repository. It can be configured to send an email notification on a script terminating error. Figure 5: PowerShell Activity Script tab: is only available to SCSM Administrators and allows you to view the script. To edit the script, double click the script name and this opens the script from the library repository. Output tab: Any output (including errors) generated by the script is displayed on this tab. By default, when a Script has a terminating error the PowerShell Activity will be marked as Failed and this will stop the workflow. On Error Continue Workflow allows the parent Work item workflow to continue even if the script has a terminating error. Note this will mark the PowerShell Activity as Completed even though it had a terminating error when running. If Email Notification is configured an email will still be sent. 10
5.6 PowerShell Activity Error Handling PowerShell has two types of errors: Non-Terminating Errors: non-serious errors that show as red output on the screen, but do not stop the script form running. They will register as Successfully Executed in the PowerShell Activity, and the output screen will capture the non-terminating error. Terminating Errors Serious errors that stop the scrip from continuing. They will cause the PowerShell Activity to fail and thus stop the entire work item workflow (use On Error Continue Workflow to override this). $ErrorActionPreference can be used to control the behaviour of non-terminating errors. Terminating errors will always stop the script from continuing. $ErrorActionPreference can make a non-terminating error behave like a terminating error ie it will fail the PowerShell Activity and cause an error email to be sent. The options for $ErrorActionPreference are: SilentlyContinue no error message displayed and execution will continue Stop a error stops the script from continuing execution Continue the default option. Errors will display and execution will continue Inquire prompt the user for input Ignore the error is ignored and not logged to the error stream Place the following code at the beginning of the script to make a non-terminating error stop: $ErrorActionPreference = Stop For more information: refer to the following blog post from Hey, Scripting Guys it has a good explanation of PowerShell error handling: https://blogs.technet.microsoft.com/heyscriptingguy/2014/07/09/handling-errors-thepowershell-way/ 11
6 Language Support and Overrides Xapity PowerShell Activity supports all languages supported by Service Manager. Translation is difficult in a technical environment and errors occur. As a result, we have given you the ability to edit the translations and import your own translations for any dialogue in Xapity PowerShell Activity. The feature to edit the translations also gives you the ability to customise the dialogue strings, task names, and form headings to be more relevant to your business requirements. Languages supported in Service Manager: CHS Chinese (Simplified) CHT Chinese (Traditional) CSY Czech DAN Danish DEU German ELL Greek ENU English ESN Spanish FIN Finnish FRA French ITA Italian JPN Japanese KOR Korean NLD Dutch NOR Norwegian PLK Polish PTB Portuguese (Brazil) PTG Portuguese RUS Russian SVE Swedish TRK Turkish ZHH Chinese (Taiwan) 6.1 Edit Translation To customise the language or to fix an existing translation, Xapity PowerShell Activity supports importing an extension Management Pack to override the language settings. In the product download zip file there is an unsealed Management Pack Xapity.PowerShellActivity.ExtendedLanguages.xml. This XML Management Pack can be edited and then imported into Service Manager. In the product download we also provided an Additional Languages folder, with a base language file for each of the Service Manager supported languages. These were translated used Bing Translator and will need to be verified before adding them to the Extension Management Pack. In each text file all the variables and labels are defined, edit the strings that are relevant and then copy them into the LanguagePack Display Strings section of the Xapity.PowerShellActivity.ExtendedLanguages.xml Management Pack. The variables referenced will override the default product values. This will fix any translation errors that were made or customise the strings to what you need. Tip: Verify the translation before importing as these were automatically translated using Bing Translator. 12
Example: Spanish XML from Text file Xapity.PowerShell Activity.ESN.Bing.Translated.txt Figure 6: Example Additional Language (not all strings shown) To change the Spanish translation or customise these strings, edit them to a more suitable translation or value. Then open the file Xapity.PowerShellActivity.ExtendedLanguages.xml and replace the green section below with the updated section of the Spanish language text file. Figure 7: Update Extended Languages XML with additional language Add as many languages overrides as required. The Xapity.PowerShellActivity.Extended.Languages.xml file is used for all 23 supported languages. Import the unsealed management pack Xapity.PowerShellActivity.ExtendedLanguages.xml into Service Manager for Xapity PowerShell Activity to support the edited translations. If you come across translation errors, either in the extended languages, please let us know. We are always trying to make our products better! 13
6.2 Override String Values It is also possible to use this method to override the default English values: Open Xapity.PowerShell Activity.ExtendedLanguages.xml Edit the values in the ENU section Import it into Service Manager. You can rebrand the tasks or add custom details to the strings and dialog boxes that are relevant to your environment. 14
7 Further Information Please refer to the following guides on the Xapity website: Xapity Reference Guide SCSM Authoring Tool Form Layout Guide Xapity Reference Guide Extend SCSM Work Items Xapity Reference Guide Type Projections Xapity Clone Xapity Mail Xapity Transfer Xapity User History Xapity Blogs including PowerShell links and examples 7.1 Xapity Support For any support issues please contact support@xapity.com. 15