Follow

Request Management for WAP - Operations Guide

 

Gridpro AB

Rev: 1.5.6522 (System Center 2012) & 2.0.6522 (System Center 2016)

Published: November 2017

 

Request Offering Configuration

Offerings available on the Tenant Portal, through Request Management for Windows Azure Pack, are Request Offerings defined in the System Center Service Manager (SCSM) Service Catalog. Creating and configuring Request Offerings is done through the SCSM Console. For a general overview of the SCSM Service Catalog and how to create Request Offerings, visit: http://technet.microsoft.com/en-us/library/hh495624.aspx

Request Offering Requirements

For a Request Offering to be available in the Request Management Wizard on the Windows Azure Pack (WAP) Tenant Portal, the following conditions must be satisfied:

  • The Request Offering is published (Offering Status is set to “Published” or “WAP”)
  • The Request Offering belongs to a Service Offering
  • The Service Offering is published

In addition to this, plan configuration can limit which Request Offerings that are available for a plan. See Plan Configuration in Request Management for Windows Azure Pack – Deployment Guide for more information.

Advanced Request Offering Configuration

In addition to the configuration options provided through the Service Manager Console natively, Request Management for Windows Azure Pack adds advanced configuration options that affect the behavior of the New Request Wizard in the Windows Azure Pack Tenant Portal. The following section describes how to access the new configuration options and provides detailed information on what each option is used for.

Accessing Advanced Configurations

Start the SCSM Console

rm-op-2.png

Click Library
 

rm-op-3.png

Click Service Catalog\Request Offerings\All Request Offerings

rm-op-4.png

Select the Request Offering you want to configure

rm-op-5.png

In the right task pane, click Advanced Configuration

rm-op-6.png

The Advanced Configuration Form is shown


Configuring Costs

Through Advanced Configuration, Request Offerings can be extended with cost information. To enable this feature, check the Is Cost Enabled checkbox.

rm-op-7.png

General Cost Configuration

When enabled, cost information can be configured in the following ways.

Formatting options

When defining a currency symbol, the default behavior will place the currency symbol before the numeric value. If you want to have a different placement of the currency symbol this can be achieved by supplying formatting information in the Currency configuration. Simply place the following symbol “{0}” where you want the numeric value for the cost to be place relatively to the currency symbol. In the following table with examples of Currency configuration, consider the base cost to have a numeric value of 100.

Currency

Result for one-time cost

Result for monthly cost

$

$100

$100.00 / Month

{0}kr

100kr

100kr / Month

Table 1. Example formatting of cost numeric value and currency symbol.

 

Base Cost

When a Request Offering is configured with a base cost, it will be displayed on the request offering selection page. In the picture below, costs are set on a monthly basis with a dollar currency.

rm-op-8.png

Prompt Cost

After enabling cost visualization by checking the checkbox for Is Cost Enabled on a request offering to show the base cost for the offering, you can choose to show how different decisions within an offering affects the total price of the offering. The following sections shows how to configure different prompts to affect the total price.

MP Enumeration List- and Simple List Prompt

Each list item can be associated with a cost, this is done by selecting a list item in the drop down called Enum item to configure and entering a value in the Cost text box. By default. the price will be shown as in the image below.

 

These are displayed in the Request Wizard in the following way.

rm-op-10.png

NOTE: When using a Simple List in combination with a Remote Source script, the cost information can be returned by the PowerShell script. For more information, see PowerShell Extensions – Remote Source.

True/False Prompt (Boolean)

Boolean prompts can be extended with costs for each choice.

This is displayed in the Request Wizard in the following way.

rm-op-12.png


Query Result

To show cost information in a query result prompt, you need to configure the property that holds the cost of each item. Supported property types are decimal, double and integer.

The resulting prompt in "New Request Wizard" shows the cost property and sums up the selected items.

 

Page/Header Configuration

User Prompts can be divided into pages in two ways, either by using the Prompts per Page setting, or by configuring the pages manually. Note that Prompts per Page configuration is done on a WAP Plan in contrast to manual configuration which is done on each separate Request Offering.

Prompts per Page

By default, User Prompts are divided into pages by using the plan setting Prompts Per Page (default: 5). For example: If the Prompts Per Page setting is set to 5 and there is a total of 12 prompts, the result will be 2 pages with 5 prompts each followed by the last page with 2 prompts.

An exception to this is the use of Query Result Prompts, which always use the full space of a page.

To configure Prompts per Page, follow these steps:

1.     Login to the WAP Admin Site

2.     Click Request Management in the left navigation pane

3.     Click Connections Tab

4.     Click the connection you want to configure

5.     Select the plan you want to configure

6.     Click Edit in the bottom action pane

7.     Enter a new value in the Prompts per Page text box (as seen in image below)

8.     Click the checkmark in the bottom right corner to save the changes


rm-op-15.png


Manual Page Configuration

Manually configuring pages lets you set exactly which prompt that should appear on each page. Configuring pages manually also gives you the option of changing the header on each page.

To configure pages/headers, open the advanced configuration of the Request Offering you want to configure and click Headers in the left navigation pane.

rm-op-16.png 


Pages are divided by headers, to add a page follow these steps:

1.     Click Add

2.     Enter a header text

3.     Click OK

4.     The header will appear last in the list of prompts and headers

5.     Move the header to the right position using the up and down arrows

To remove a header, simply select the header and click Remove.

The Page column shows the page number to give you a sense of how the prompts will be displayed in Request Wizard.

PowerShell Extensions

Request Management for Windows Azure Pack has the possibility to use PowerShell to retrieve data that should be presented in a form as well as use PowerShell to validate input entered in a form, the two capabilities are referred to as Remote Source and Remote Validation. The PowerShell scripts used for Remote Source and Remote Validation are executed through the Request Management API web service, therefore the location used to store the scripts needs to be accessible from the web service. The script folder path is set in the configuration file called solidNonSensitiveSettings.config placed in the Request Management API installation folder (typically "C:\inetpub\MgmtSvc-RequestManagementAPI\"). The default script folder path is “C:\Scripts” but can be changed by editing the “ScriptPath” parameter shown in image below.

rm-op-17.png

Script Parameters

Remote Source and Remote Validation scripts both carries the parameters called userContext and formContext. These parameters contain data that is crucial when building rich user experiences within your forms.

Name

Purpose

Availability

userContext

Provide information about user and current subscription.

Remote Source
Remote Validation

formContext

Provide information about Questions (Prompts) and currently available answers.

Remote Source
Remote Validation

actionContext

Provide information about object associated with the current request, for more information see Request Actions.

Remote Source

valueToValidate

Contains the current value of the prompt associated with the remote validation script.

Remote Validation

 

User Context Parameter

The parameter userContext is available on both Remote Source and Remote Validation scripts. The purpose of the parameter is to pass user context information to the script. The parameter contains the following properties.

Name

Description

SubscriptionId

The SubscriptionId parameter is the id of the Windows Azure Pack subscription currently in use. This can be used in scenarios when there is a need to get information related to the WAP subscription, such as which Virtual Machines that are associated to the VM.

Claims

The Claims property is a list of claims currently accessible from the logged-on user, in the current version the only claim available is the logged-on user's User Principal Name (UPN) which can e.g. be used to retrieve more information about the user from Active Directory.

LanguageCode

The LanguageCode is the code of the language currently selected in the portal. This can be used to return remote source data or validation error messages in the same languages as chosen in WAP.


 

The context data can be accessed as below.

 

Param(

    [PSObject]$userContext,

    [PSObject]$formContext,

    [PSObject]$actionContext

)

#Id of the subscription currently in use

$SubscriptionId = $userContext.SubscriptionId

 

#Language Code representing the currently selected language e.g. en-US

$UserLangCode = $userContext.LanguageCode

 

#Claims available for the currently logged on user

foreach($claim in $userContext.Claims) {

    $ClaimType = $claim.Type

    $ClaimValue = $claim.Value

}

Form Context Parameter

The parameter $formContext is available on both Remote Source and Remote Validation scripts. The purpose of the parameter is to bring the form information to the script. The parameter has the following properties.

Name

Description

RequestOffering

The RequestOffering property has information of the selected request offering and includes the properties Name and Id.

Prompt<Number>

Each prompt is represented as a property on the $formContext. For detail on each prompt see the next table.

Each prompt has the following properties.

 Name

Description

Id

The id of the prompt, owned by the configuration in SCSM.

ScriptId

The ScriptId of the prompt, this is visible in the Advanced Configuration Wizard in the SCSM console.

PromptType

Text = 0,

MultiLineText = 1,

DropDown = 2,

DateTime = 3,

Boolean = 4,

Integer = 5,

Decimal = 6,

File = 7,

InstancePicker = 8,

Enum = 9

AssignedValue

The value of the current prompt. This is applicable for all prompts except for a Query Result Prompt configured to allow multi select.

AssignedValues

The value of the current prompt. This is only for a Query Result Prompt configured to allow multi select.

Text

The label of the prompt.

 

Accessing Prompt Data from PowerShell

Each prompt in a request offering receives a script id that can be found by opening the “Advanced Request Offering Configuration” window in the SCSM console (as seen in image below). The script id is used to locate the specific prompt from within a script used as a Remote Source- or Remote Validation script.

 

 

The script id is used from within a script to retrieve the current value of a prompt from the “formContext” parameter, as seen highlighted in Table 1.

Param(

    [PSObject]$userContext,

    [PSObject]$formContext,

    [PSObject]$actionContext

)

$role = $formContext.Prompt2.Answer.Value

...

 

Action Context Parameter

The parameter actionContext is only available in Remote Source scripts. The purpose of the parameter is to bring information about the resource that was selected when a Request Action has been used to initiate the New Request Wizard for a resource. For more information about this type of action, see Request Actions.

The parameter contains the following properties.

Name

Description

Item

The Item property is the resource from which the request was triggered.

Example: The Action “Order more RAM” is triggered from inside the computer form. The actual computer will be sent as Action Context to the script.

RelatedItem

The related item property is only set if the request was triggered with a related item selected on the related items page of a resource.

Example: From inside the related items tab of the computer form, a related Incident is selected and the action “Resolve Incident” is triggered. This will start the request wizard with item set to the computer and the related item set to the incident.


Both the Item and RelatedItem properties contains the following properties.

Name

Description

Id

The internal id of the resource as it is defined in the CMDB of SCSM.

DisplayName

The display name of the resource as it is defined in SCSM.

Types

An array of strings that describes the class hierarchy for the resources as it is defined in SCSM.

 

The action data can be accessed as below.

Param(

    [PSObject]$userContext,

    [PSObject]$formContext,

    [PSObject]$actionContext

)

 

#Get the internal SCSM Id from the selected Item

$resourceInternalId = $actionContext.Item.Id

 

#Get the SCSM DisplayName from the selected Item

$resourceDisplayName = $actionContext.Item.DisplayName

 

#Get the class hierarchy of the SCSM representation of the selected resource

$itemClasses = $actionContext.Item.Types

 

#Get the SCSM DisplayName of the selected related item

$relatedResourceDisplayName = $actionContext.RelatedItem.DisplayName

...

 

 

"Value To Validate" Parameter

The parameter valueToValidate is only available in Remote Validation scripts. The purpose of the parameter is to bring information about the current user input. The parameter is a simple property of the type you define it as in the script (normally string). See Remote Validation for examples on how to use the parameter.

Remote Validation

In addition to the built-in validation rules configurable in the Request Offering Wizard in SCSM, user input can be configured to be validated using PowerShell scripts.

The script takes the value as a parameter and should return a PowerShell Custom Object with the two properties IsValid and ValidationMessage. The following script is an example of how to validate that the value is less than 35.

#

# Remote Validation Example script

#

Param(

    [PSObject]$userContext,

    [PSObject]$formContext,

    [Parameter(Mandatory=$true)]

    [string]$valueToValidate

)

 

#Make sure the input is of correct type

[int]$value = -1

if(![int]::TryParse($valueToValidate,[ref]$value))

{

    return New-Object PSCustomObject -Property @{

            IsValid = $false

            ValidationMessage = "The input cannot be parsed to an integer."

       }

}

 

#Time for validation. Make sure the "value is an integer less than 35"

if ($value -lt 35)

{

    #Tell the "New Request Wizard" the input is valid

    return New-Object PSCustomObject -Property @{

        IsValid = $true

        ValidationMessage = ""

        }  

} else

{

    #Tell the "New Request Wizard" the input is not valid

    return New-Object PSCustomObject -Property @{

            IsValid = $false

            ValidationMessage = "The value needs to be less than 35"

       }

}

 

Configuring Remote Validation

To configure remote validation for a user prompt, please follow these steps.

1.     Open the Request Offering Advanced Configuration

2.     Click Prompts in the left navigation pane

3.     Select the prompt to configure remote validation for

4.     Check Is Remote Validation Enabled

5.     In the Remote Validation Path, enter the name of the script to run when validating

Note: If you only enter the name of the script this indicates that the script is placed directly beneath the script path shown in
image above in section "PowerShell Extensions". If you organize your scripts in sub folders, you need to include the sub folder name (e.g. “ValidationScripts\ValidationExample.ps1”).

Remote Source

Instead of using static values, Simple List-, Integer-, Decimal- and Text Prompts can be configured to be populated from the result of a script execution.

Script Output Requirements

When used to populate a Simple List Prompt the script should return an array of PowerShell Custom Objects, each with the following properties:

  • DisplayName: The text to show for the list item
    Note: This value is the value is shown in UserInput of a request
  • Value: The value that should be set when selecting this list item
    Note: This value is set on the property mapped to the prompt in the Request Offering definition
  • Cost: An object with only one property called Value that holds the cost of the list item
    Note: Cost is an optional property
  • Children: An array of custom objects representing child objects
    Note: Children is an optional property
  • IsDefault: A Boolean that toggles whether the item should be selected by default or not, only one item in the list should have this value set to true
    Note: IsDefault is optional, if not set, no item will be set by default


The following script provides an example on a script returning data to a Simple List Prompt.

#

# Remote Source example script

#

Param(

    [PSObject]$userContext

)

 

$rootItems = @()

 

$rootItems += New-Object PSCustomObject -Property @{

    DisplayName = "Item 1"

    Value = "1"

    Cost = New-Object PSCustomObject -Property @{

        Value = 240

    }

    Children = @(

        New-Object PSCustomObject -Property @{

            DisplayName = "Item 1.1"

            Value = "1.1"

            Cost = New-Object PSCustomObject -Property @{

                Value = 120

            }

            Children = @()

        }

    )

}

 

$rootItems += New-Object PSCustomObject -Property @{

    DisplayName = "Item 2"

    Value = "2"

    Cost = New-Object PSCustomObject -Property @{

        Value = 240

    }

    Children = @()

}

 

return  $rootItems 

 

 

The following script provides an example on how to return data to an Integer-, Decimal- or Text Prompt.

#

# Remote Source example script

#

Param(

    [PSObject]$userContext,

    [PSObject]$formContext,

    [PSObject]$actionContext

)

 

$item = New-Object PSCustomObject -Property @{

    DisplayName = "Sample text"

    Value = "N/A"

}

 

return  $item

 

 

Configuring Remote Source

1.     Open the Request Offering Advanced Configuration

2.     Click Prompts in the left navigation pane

3.     Select the list prompt to configure remote source for

4.     Select Use Remote Source

5.     Enter the name of the script to execute

 

Prompt Dependencies

When working with dependencies between prompts it can be useful to be able to configure when a PowerShell script for Remote Source or Remote Validation should be triggered to run again. This can be done through the Refreshed By settings for Remote Source and Remote Validation.

Consider the following example, in Image below, the prompt called “Question 4” is displayed as a list that is configured to use a PowerShell script to retrieve list items. If the PowerShell script configured to retrieve the data is using the currently selected value of “Question 3” to figure out which list items to return to the form, you want the list in “Question 4” to be refreshed each time the value of “Question 3” changes. This is achieved by setting the Refreshed By setting, of “Question 4”, to “Question 3”.

The same way as the example above described how to configure refresh triggers for a Remote Source script, Remote Validation scripts can be configured to re-validate the form data based on previous prompts changing values.

Conditional Visibility

It is possible to dynamically control when to show and hide prompts within the Request Wizard. Visibility is controlled by a PowerShell script that sends back a list of prompts that should be visible at a given moment. Within the script, you can reach the value of each prompt and use this to decide which prompts you want show based on those values.

To enable the feature, open the Advanced Configuration dialog for a specific request offering and write the name of the script you want to use in the Conditional Visibility section.

image15.png

Once configured, place a script with the given name in the same folder as your Remote Source/Remote Validation scripts. The following section describes how to compose your visibility scripts.

The script declared in the Conditional Visibility section will be asked to provide a list of prompts that should be visible in the UI based on the current user input. By sending back a list of prompts (“Script Id”) the UI knows which prompts to show. Any prompt NOT represented in the list sent back from the script will be hidden. The script will execute when entering the wizard for an offering and each time a prompt value changes. This means it will execute quite often which mean you will need to keep it fast and simple. We recommend NOT doing any external calls to e.g. web services in these scripts.

Example

As a simple example, let’s say you have two prompts in a request offering. The prompts are Prompt0 (textbox) and Prompt1 and you don’t want to show Prompt1 until Promp0 has a value. This can be achieved using the following script.

# VisibilityMap Script Example

 

Param(

    [PSObject]$userContext,

    [PSObject]$formContext,

    [PSObject]$actionContext

)

$valueOfPrompt0 = $formContext.Prompt0.Answer.Value

$visiblePrompts = @("Prompt0")

 

if(![string]::IsNullOrEmpty($valueOfPrompt0)){

    $visiblePrompts += "Prompt1"

}

 

$result = New-Object PSCustomObject -Property @{

    VisiblePrompts = $visiblePrompts

}

 

return  $result


The following script can be used to demonstrate the functionality. It will show the next prompt in order as soon as a value has been added to a prompt.

# VisibilityMap Script Example

 

Param(

    [PSObject]$userContext,

    [PSObject]$formContext,

    [PSObject]$actionContext

)

$visiblePrompts = @()

 

$temp = $formContext|Select-Object -Property Prompt*

$prompts = $temp|Get-Member -MemberType NoteProperty|Select-Object -ExpandProperty Name

 

foreach($promptName in $prompts)

{

    $visiblePrompts+=$promptName;   

    if([String]::IsNullOrEmpty($formContext.$promptName.Answer.Value))

    {

        break

    }  

}

 

$result = New-Object PSCustomObject -Property @{

    VisiblePrompts = $visiblePrompts

}

 

return  $result

 

General Considerations for PowerShell Extensions

Load Balancing – If you have load balanced your Request Management API web service, make sure you either use a shared location for your scripts or keep all stores in sync when it comes to script changes. It is also important to remember that you need to point out any custom script path in the configuration file for each web service as described earlier in this section.

Permissions – The account running the Request Management API application pool (MgmtSvc-RequestManagementAPI) is the account that will execute the remote validation scripts. Hence this account needs to have the appropriate permissions to do so.

Script Output – Avoid using “Write-Output” in the PowerShell script since it will add un-expected objects to the output and, in worst case, make the Request Management API web service crash.


Legal Acceptance

A Request Offering can be configured to show a legal acceptance text that needs to be accepted when registering a new request. The legal acceptance page in the Request Offering Wizard in WAP is shown before the last page and can be configured with a custom label and acceptance text.

rm-op-20.png

The Legal Acceptance Text accepts any HTML formatted text. To adjust how the text is displayed to the user use the available HTML tags (example: <i>, <b> and <h1>).

The configured acceptance page will be displayed as below.

rm-op-21.png

 

General Prompt Settings

Include in User Input

By default, the information a user enters in the request wizard is written to the UserInput field of the resulting request. This behavior can be changed on a per prompt basis. This is done by unchecking the “Include in User Input” checkbox.

Tooltip

Adding a tooltip to a prompt is done by simply entering a text in the tooltip textbox.

If a prompt has a tooltip set, it will show up as a question mark next to the prompt in the Create Request Wizard like below:

Text Prompts

The text prompt can be displayed in three different ways:

  • Default
  • Multiline
  • Password

By default, text prompts are displayed as a single line text box:

If multiline is checked, the prompt will be displayed as below:

If Password is checked, the input will be masked as below:

If configured as Password, the value will also be masked in the User Input section of the request created in Service Manager. However, if the password prompt is mapped to a property in SCSM, this value will be available on that property in clear text. If you wish to secure the password, Request Management can be configured to encrypt the password using a certificate, for details see the Portal Configuration section.

 

Boolean Prompts (True/False)

Custom labels for toggle buttons, used to represent a Boolean value, can be set through the advanced configuration as shown below.

 

The result from the configuration above is shown in the image below.

rm-op-23.png

 

 

Resource Management

In the Resources section of the Tenant Site a tenant can manage resources normally not available in Windows Azure Pack. These resources are Configuration Items in the System Center Service Manager environment connected to Windows Azure Pack. The Resource space on the Tenant Site contains three major features, listing the resource associated to a Tenant, customizable forms- and actions per type of resource (class type in the Service Manager CMDB).

rm_op_image_19.png

Exposing Resource from the CMDB

For resources to appear in the Resource Management space of the Tenant Site one of two conditions needs to be fulfilled. These conditions differ based on which mode you are running Request Management in, Subscription- or User Mode. For more information about the two different modes, see Plan Settings in the Request Management for Windows Azure Pack – Deployment Guide. The following sections explain the two different conditions that need to be fulfilled for resources to appear.

Resource Management in User Mode

For resources to appear when running in "User Mode" (configured through Plan Settings as seen in the image below) the user needs to be set as a custodian on a configuration item in the CMDB of System Center Service Manager. This means that Windows Azure Pack needs to be able to find a user in the Service Manager CMDB with a User Principal Name (UPN) matching the logged-on user’s User Name in WAP.

rm_op_image_20.png

In the next image below the User Form in System Center Service Manager is showing that the user is custodian on the azuredev021 computer object. In the image below the same computer is shown on the WAP Tenant Site.

rm_op_image_21.png

Resource Management in Subscription Mode

For resources to appear on the Tenant Site, in the Resource space, when running in Subscription Mode there must be a relationship established between an object representing the WAP Subscription and the Configuration Item in the CMDB.

The relationship is a custom relationship class that is added to Service Manager when you install the Request Management for Windows Azure Pack: API through import of a Management Pack.

Using Subscription Mode instead of User Mode enables users to share management of resources in the same way as co-admins of a subscription would share management of any other resource within Windows Azure Pack.

Example of usage

When using Request Management for Windows Azure Pack it is possible to create an offering that will collect data and trigger an automation process using the collected data to provision a User Account in Active Directory (or e.g. a Virtual Machine in Azure). During the automation process (e.g. a Service Management Automation runbook) a configuration item can be added to the Service Manager CMDB and the required relationship can be established to allow management of the newly provisioned resource within the Windows Azure Pack Tenant Portal. Combine this with the possibility of creating custom actions (see Action Configuration chapter later in this document) to enable full lifecycle management for custom resources.

Provided with this documentation comes a set of example scripts, included is the script “Set-ConfigItemToWAPSubRelationship.ps1”. This is a good example of how the required relationship can be established in the CMDB. See below for usage instructions.

rm_op_image_22.png

 

Action Configuration

Resource Management for Windows Azure Pack introduces the concept of actions. Actions are presented to users in three views as shown below.

  • When selecting a resource in the list of resources

rm_op_image_23.png
  

  • On the Resource Details page

rm_op_image_24.png

  • When a Related Item is selected on the Related Items Tab

rm_op_image_25.png

 

Runbook Actions

Using a Runbook Action within Resource Management will trigger a runbook in Service Management Automation (SMA). When the triggered runbook is executed, three properties will be passed that can be used to enable different automation scenarios. The following sections describes the parameters provided.

Script Parameters

The following parameters are always passed to a SMA Runbook triggered by a Runbook Action from within Resource Management.

Name

Purpose

ResourceManagementResourceId

 

The identifier of the selected resource, this is the same as the internal identifier of the configuration item (the resource) in the Service Manager CMDB.

ResourceManagementPropertyBag

 

Contains data about the selected resource, fetched from Service Manager. See detailed description in section ResourceManagementPropertyBag Parameter

ResourceManagementUserContext

 

Provide information about user and current subscription. See section User Context Parameter since this has the exact same data.


IMPORTANT: To be able to access the parameters from within the runbook you need to declare them in the runbook parameters section as below.

param(

        [parameter(Mandatory=$true)]

        [PSObject]$ResourceManagementPropertyBag,

       

        [parameter(Mandatory=$true)]

        [String]$ResourceManagementResourceId,

 

        [parameter(Mandatory=$true)]

        [PSObject]$ResourceManagementUserContext       

    ) 

 

 

ResourceManagementPropertyBag Parameter

Contains data (from Service Manager) about the resource that the runbook should be executed against. The property bag parameter consists of two parts:

1.     Object property

2.     Relations property

 

The Object property consists of the following data.

Name

Description

Id

The id of the resource.

SubscriptionId

The id of the subscription this resource belongs to.

DisplayName

The display name of the resource.

Status

The status of the resource. This property is used internally by the extension and it is not recommended to use this property in custom scripts.

A better approach to determine the status of the resource would be to fetch the resource directly from Service Manager.

Type

The type of the cloud resource. This property is used internally by the extension and it is not recommended to use this property in custom scripts.

TypeName

The name of the type that the resource has in Service Manager.

Types

A list of ids of all the types that the resource has in Service Manager. The list of types is based on the inheritance chain of the type that the resource represents.

The Relations property consists of a list of related items of the selected resource. The relations that are loaded are based on the FormDeclaration of the resource (for more information about form declarations see Resource Forms) and will vary depending on what type the resource has. The following relations are examples of what is available for the Microsoft.Windows.Computer type out of the box:

  • Custodian
  • Processor
  • NetworkAdapter
  • PhysicalDisk
  • LogicalDisk
  • PrimaryUser

A preview of how the different parameters will look like for a specific resource type is available through the Admin Extension. To see a preview of the properties that will be sent into a runbook, do the following.

Login to the WAP Admin Site

Select the Request Management extension

Select the Action tab

Select an Runbook Action and click on the Example command

rm_op_1.png

A dialog opens that displays a generated example on how the parameters could look like

User Context Parameter

The parameter userContext has the same definition as for available on both Remote Source and Remote Validation scripts. The purpose of the parameter is to bring the user context information to the script.

Add/Edit Runbook Action

Login to the WAP Admin Site

rm_op_2.pngClick Request Management

Click Actions tab

rm_op_3.png Click Add in the bottom drawer

Provide a name for the action, this is the text that will be displayed to users on the Tenant Site

rm_op_4.png

In the resource type dropdown, select the type of resource that the action should be available for. Derived types of the specified resource type will also be eligible for the action.


Example: Specifying Computer from the list will result in the action being available for all resource of type computer, but also derived types like Windows.Computer. This means that choosing Configuration Item will make the action available for all resources, since all resource types derive from Configuration Item.

For Action Type, leave Runbook selected and click Next

For Context Type, select one of the following:

1.     General: The action will be displayed when selecting a resource (that matches the target type of the action) in the resource list and resource details pages

2.     Related Item: The action will be displayed when selecting a related item for a resource in the related item tabs (that matches the target type of the action)

rm_op_5.png

Next, choose an icon that will be displayed along with the name

rm_op_6.png

Finally, choose the Runbook to run when this action is triggered and click the checkmark to complete the wizard

 

Request Actions

Request actions will open the Create Request Wizard in Request Management for WAP. When opened, the configured offerings will be selected. The resource selected when the action was triggered will populate the first matching query prompt for the Request Offering.

Information about the resource that was selected when the action was triggered is also available for the Remote Source PowerShell scripts hooked up to prompts in the Request Wizard. The information is accessible through the $actionContext parameter described in the Action Context Parameter section of this document.

For information on how to create a new Request Action, follow these steps.

Login to the WAP Admin Site

rm_op_7.pngClick Request Management

Click Actions tab

rm_op_8.png Click Add in the bottom drawer

Provide a name for the action, this is the text that will be displayed to users on the Tenant Site

rm_op_9.png

In the resource type dropdown, select the type of resource that the action should be available for. Derived types of the specified resource type will also be eligible for the action.

Example: Specifying Computer from the list will result in the action being available for all resource of type computer, but also derived types like Windows.Computer. This means that choosing Configuration Item will make the action available for all resources, since all resource types derive from Configuration Item.

For Action Type, select Request and click Next

For Context Type, select one of the following:

1.     General: The action will be displayed when selecting a resource (that match the target type of the action) in the resource list and resource details pages.

2.     Related Item: The action will be displayed when selecting a related item for a resource in the related item tabs (that match the target type of the action).

rm_op_10.png

Choose an Icon that will be displayed along with the name

rm_op_11.png

Finally, choose the Service Offering and Request Offering  to be selected when the request wizard is started. Complete the wizard by click the check mark

 

Resource Forms

Each resource type (class type in Service Manager) can have its own visual appearance on the details page within Resource Management. The visual appearance is controlled by format files available after installing the Request Management for Windows Azure Pack: API. After installation, there are a number of predefined forms available at (based on a default installation):
C:\inetpub\MgmtSvc-RequestManagementAPI\App_Data\FormDeclarations

A format file is named the same as the resource type it should be associated with. The following files are provided out of the box:

  • System.Domain.User.xml
  • System.ConfigItem.xml
  • Microsoft.Windows.Computer.xml

When trying to locate a form for a Configuration Item the complete class hierarchy (for the configuration item within Service Manager) is considered. If no form is available for the most specific class, the process moves up the hierarchy until it finds a form. This means that the ultimate fallback form is System.ConfigItem.xml.

Custom Form Declarations

If you want to add your own format for a resource type the file should be named with an “Override” suffix to ensure that Gridpro never overwrites this format file if provided one for the same type out of the box.

This means if you want to add a form for a resource of type “BusinessService” you should name the file: Microsoft.SystemCenter.BusinessService.Override.xml

The easiest way to get started is to copy one of the existing form declarations, rename and modify it. The standard form declarations contain guidance on how to do the declaration.

Extension Translation

Out of the box Request Management for Windows Azure Pack contains translations for the Resource extension name in the Portal for all supported languages.

rm_op_image_26.png

 

If the name of the Resource extension does not match the naming convention within the organization (example: The word resource may mean something different for different people), then it is possible to provide custom translations.

To provide custom translations for the Resource extension, perform the following steps.

Locate web.config in the tenant site (example: C:\inetpub\MgmtSvc-TenantSite\web.config)

Add the following value under the <appSettings> node:

<add key="ResourceManagement.ExtensionTranslation" value="<LanguageCode>;<Translation>|<LanguageCode>;<Translation>" />

Replace <Languagecode> with the corresponding language codes you want to change translation for and the <Translation> with the actual translation

Example:

<add key="ResourceManagement.ExtensionTranslation" value="en-US;Example1|de-DE;Example2” />

The above example will add a translation for English and German where the title of the extension will be translated to Example1 and Example2 depending on which language the user has picked in the portal

Save the changes and reload the Tenant site in the browser

The name of the extension should now use the custom translation instead of the one provided out of the box

rm_op_12.png

IMPORTANT: If multiple Tenant sites are available in your environment the web.config has to be changed for all of them

 

Portal Configuration

The tenant portal experience can be configured in a number of ways:

  • Disable Cancel Request
  • Add additional columns to the Requests page
  • Add additional columns to the Activities page
  • Add additional columns to the Resources page
  • Filter Requests on the Requests page
  • Filter Activities on the Activities page
  • Enable automatic update on the Activity- and Request Details pages

All settings are configured by changing application settings in solidNonSensitiveSettings.config found in the Request Management API installation folder (c:\inetpub\MgmtSvc-RequestManagementAPI).

Disable Cancel Request

To prevent users from being able to cancel a request, set the application setting “CancelRequestEnabled” to “false” as below:

<add key="CancelRequestEnabled" value="false" />

Add additional columns to the Requests/Activities/Resources page

The columns shown on the Request/Activities/Resources page can be extended with other properties. Each column is configured with a DisplayName to be shown as column header, a PropertyName, an optional Type and an optional Ordinal for ordering. Not setting the Ordinal will add the column last. Type is used for date time properties and should be set to ‘DateTime’ in those cases. Generic properties can be shown using the dollar signs around the PropertyName, like $LastModified$.

The setting is configured using a JSON formatted list of columns to be added. An example of how a configuration for the Resources page can look like:

[  
   {  
      DisplayName:'Principal Name',
      PropertyName:'PrincipalName'
   },
   {  
      DisplayName:'Last Modified',
      PropertyName:'$LastModified$',
      Type:'DateTime'
   }
]

 

The setting of the example above for the resources page would look like:

<add key="AdditionalResourceColumns" value="[{DisplayName:'Principal Name', PropertyName:'PrincipalName' }, {DisplayName:'Last Modified', PropertyName:'$LastModified$', Type:'DateTime'}]"></add>

List of generic properties

  • $LastModified$
  • $Type$
  • $DisplayName$
  • $Id$
  • $FullName$
  • $Name$

Status filters

The Requests and Activities pages can be configured to show only work items with a specific set of statuses. Each status is separated with a semi colon. The following example configures the Activities page to only show Completed and In Progress Activities:

<add key="ActivityStatusFilter" value="ActivityStatusEnum.Completed; ActivityStatusEnum.Active" />

 

See configurable values for activities below.

Activity Statuses

Configuration Value

Completed

ActivityStatusEnum.Completed

Cancelled

ActivityStatusEnum.Cancelled

Skipped

ActivityStatusEnum.Skipped

In Progress

ActivityStatusEnum.Active

On Hold

ActivityStatusEnum.OnHold

Failed

ActivityStatusEnum.Failed

Rerun

ActivityStatusEnum.Rerun

Pending

ActivityStatusEnum.Ready

 

This example configures the Requests page to only show Active and Pending Incidents.

<add key="RequestStatusFilter" value=" IncidentStatusEnum.Active ; IncidentStatusEnum.Active.Pending ">

 

See configurable values for requests below.

Incident Statuses

Configuration Value

Active

IncidentStatusEnum.Active

Closed

IncidentStatusEnum.Closed

Pending

IncidentStatusEnum.Active.Pending

Resolved

IncidentStatusEnum.Resolved

 

Service Request Statuses

Configuration Value

New

ServiceRequestStatusEnum.New

Closed

ServiceRequestStatusEnum.Closed

Completed

ServiceRequestStatusEnum.Completed

Failed

ServiceRequestStatusEnum.Failed

Cancelled

ServiceRequestStatusEnum.Canceled

On Hold

ServiceRequestStatusEnum.OnHold

In Progress

ServiceRequestStatusEnum.InProgress

Submitted

ServiceRequestStatusEnum.Submitted

 

Change Request Statuses

Configuration Value

New

ChangeStatusEnum.New

Closed

ChangeStatusEnum.Closed

Completed

ChangeStatusEnum.Completed

Failed

ChangeStatusEnum.Failed

Cancelled

ChangeStatusEnum.Cancelled

On Hold

ChangeStatusEnum.OnHold

In Progress

ChangeStatusEnum.InProgress

Submitted

ChangeStatusEnum.Submitted

 

Password Encryption

Request Management for Windows Azure Pack allows you to use RSA encryption to protect passwords from being stored in clear text in Service Manager. These can later be decrypted in e.g. an Orchestrator or Service Management Automation runbook as long as the runbook has access to the same certificate used for encryption.

Enable Password Encryption

To enable RSA encryption of passwords entered in the Create Request Wizard:

  1. First make sure that the certificate to use is imported to the local machine store on the server running Request Management API.
  2. Open the configuration file called “solidNonSensitiveSettings.config”. Typically placed in "C:\inetpub\MgmtSvc-RequestManagementAPI\solidNonSensitiveSettings.config"
  3. Set the EncryptionCertificatePath value to “Store Location\Store Name\Thumbprint”
    Example: <add key="EncryptionCertificatePath" value="LocalMachine\My\ 9FDD5A36ECD2040625F77ED691B4F2B2B57AD834"></add>

Tip: To list certificates in the local machine certificate store, use the following PowerShell command:

Get-ChildItem -Path Cert:\LocalMachine\My\

 

Decrypt Password

When using RSA encryption for passwords the value stored in Service Manager is a base64 encoded representation of the encrypted data. To decrypt the data in e.g. a SMA runbook you need to make sure the certificate is available to the runbook worker (the server where the runbook is executed). The certificate needs to contain the private key and the account used to access the certificate needs to have access to the private key. Below is a PowerShell example of how to decrypt a base64 encoded string using a certificate stored in the local machine certificate store.

#Payload represents the encrypted password from Service Manager

$payload = "QKDFbA6x429Nxjqyt33pNTZ7FamKIg60aU5iVGbBj9YJdWd35fQA+4c2r0V+hYPIWymtD/0EBHCHo2gmV2iSax1DbZPn6WKy/B8X2B1nDScbT4Q0MI9HCLPP8k3o0rbuWEHkbD8JjsVYdnkWAGEYw1R9t3+4MvuNGZupkhmdtsAO3roTIM7yPi9Z1Xdm8b+oci84mowyXB3bgLhSqc5NUVRsfKb+2KuZ5Iex3AUhmAOVHCdIecoq91Esopxyw2aHoaw96Fayj1G5SVJOjD2wc3OQOSYwap3jCAGigxGIZxYVCo0X9WEj7vwPVbcW3ZP6CxWIxukdoXZi3eZS7d5o1w=="

 

#Get encrypted bytes from Base64 string

$bytesEncrypted = [System.Convert]::FromBase64String($payload)

 

#Get certificate using path

$cert = Get-Item -Path Cert:\LocalMachine\My\FD3B4D99C4E7F1F7F3F38B15A47CF86374179E94

 

#Decrypt bytes

$bytesDecrypted = $cert.PrivateKey.Decrypt($bytesEncrypted, $false)

 

#Convert decrypted bytes to string

$decryptedText = [System.Text.Encoding]::UTF8.GetString($bytesDecrypted)

 

#Decrypted text

$decryptedText

 

 

Automatic Update of Request/Activity/Resource Details

The detail pages can be configured to be updated automatically. This is done by setting the number of seconds between each update. The example below will trigger an update of the detail pages every 20 seconds:

<add key="FastPollingInterval" value="20" />

Warning: The lower value you use, the more data will be sent over the network and the more load you will put on the Service Manager Management Service.

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments