Customizing Service Request Forms

Commander includes default service request forms for new service requests and service change requests (including decommissioning and resource changes). You can customize these default forms to better support your existing service request and provisioning process.

You can access request form values through workflow variables. See Example: Mapping Request Form Fields to Variables.

Access through:

Configuration > Self-Service > Forms tab

Available to:

Commander Roles of Superuser and Enterprise Admin

In this topic:

About service request forms

New service request forms contain two sections:

  • Service section: These settings apply to a service as a whole. Ownership, expiry date, estimated cost and deployment destination are examples of service-level settings. You configure these settings in the Form Designer, as detailed in this topic. Service-level settings appear in the Service section of the New Service Request dialog.
  • Component section: Settings such as CPU, memory, network and credentials are component-specific. You configure these settings in the service catalog blueprint. Component-level settings appear in the Component section of the New Service Request dialog.

Change request forms have only a single section and are configured in the Form Designer, as detailed in this topic.

If you upgraded from release 5.2 or earlier, all existing service catalog entries use the "legacy" model by default, and any Component forms you customized are still used. f you want to continue using the legacy model, see "Customizing Legacy Service Request Forms" topic in the vCommander User Guide for Versions 5.5—7.5.

Other ways of customizing requested services

Adding elements to a request form is only one of the ways that a requested service can be customized. For example, if you want to let your users specify a value for a custom attribute, add the Custom Attribute element to a form. If you don't want user input, add a custom attribute to the Attributes tab in the service catalog blueprint; you can specify a default value or leave it blank for an administrator to enter during manual deployment. You can also specify a custom attribute value during automated deployment by adding a Set Custom Attribute step to a completion workflow.

The order of precedence for assignment of service settings during the request process is as follows (the first item in the list takes precedence):

Form visibility

When you create custom service request forms, the users or groups you assign will see one of the forms assigned to them, rather than the global Default Service form. A user can be assigned only one New Service Request form. However, you can assign any number of Service Change Request forms to a user, and the user will be prompted to select a form when requesting a service change.

Forms are shown to users in the following order of precedence (the first item in the list takes precedence):

  • Forms assigned directly to a user
  • Forms assigned to a user's organization
  • Forms assigned to a user's directory services group
  • Otherwise, the global form is displayed

For change requests, request form visibility also depends on the type of service selected. For example, a form that contains CPU and memory elements won't be available for virtual services, load balancers, application stacks, auto scaling groups and databases. For non-VM services, we recommend creating one or more change request forms with no resource elements.

Example: Creating a new service request form

For this example, we added a service called "Developer Service" to the service catalog. It contains two components: a VM component called "Windows Server 2008 R2" and a custom component called "SQLServer".

When a user requests this service, they see a request form similar to the following:

New Service Request
  • The section labeled "Developer Service" is based on the Default Service form for new service requests.
  • The section labeled "Windows Server 2008 R2" is based on the Form tab in the component's service catalog blueprint.
  • The section labeled "SQLServer" is based on the Form tab in the component's service catalog blueprint.

Creating new forms

To supplement the default service request forms Commander provides, you can create additional forms for different users and groups, and for different types of services.

To create a New Service Request form

To create a Service Change Request form

  1. Click Add in the Form Library panel.

    As a shortcut, you can also select an existing form in the Form Library and click Copy.

  2. In the Add Request Form dialog, enter a form name.
  3. Enter a Display Name if you want Service Portal users to see a different form name in request emails and in the list of service requests.
  4. If the Form Type menu is displayed, select New Request Service Form.
  5. Specify who should have access to this form.

    There can be only one global new service request form, so all other forms must be assigned to specific organizations, users and groups.

    On the Organizations tab, select an organization as required and click Add.

    On the Users/Groups tab, enter user or group IDs or email addresses as required and click Add.

  6. Click OK.

Continue to Designing a form's appearance and content.

  1. Click Add in the Form Library panel.

    As a shortcut, you can also select an existing form in the Form Library and click Copy.

  2. In the Add Request Form dialog, enter a form name.
  3. Enter a Display Name if you want Service Portal users to see a different form name when they need to choose from multiple forms, in request emails and in the list of service requests.
  4. If the Form Type menu is displayed, select Change Request Form.
  5. In the Target Type drop-down list, if you want this form to be available for managed systems, select Managed Systems. Otherwise, select Inventory. Forms that target managed systems support a limited number of form elements.
  6. From the Completion Workflow menu, choose a completion workflow that will run once change requests submitted with this form are fulfilled.

    For example, if you're creating a decommissioning request form, associate this request with a decommissioning workflow.

  7. If you want this form to be visible to specific users only, choose Publish - Specific organizations, users and groups.

    On the Organizations tab, select an organization as required and click Add.

    On the Users/Groups tab, enter user or group IDs or email addresses as required and click Add.

  8. Click OK.

Continue to Designing a form's appearance and content.

Designing a form's appearance and content

When you select a form in the Form Library panel, its contents are displayed in the Form Designer. You can add, edit and reorder elements. See Form elements available for new service requests and Form elements available for service change requests for the complete list of form elements.

To modify a selected request form, do any of the following:

  • To add a new field, click an element in the Toolbox on the right. The element is added to the bottom of the form. Customize the element as required and click OK.
  • To make a field mandatory, enable the Required checkbox. Mandatory fields are marked with an asterisk (*) in both the Form Designer and on request forms.

  • To modify an element, select it and click Edit. To save, click OK.
  • To create relationships between form fields, so that the value selected for one element affects the selectable values for another, see Creating relationships between custom attributes.
  • To change the order in which the elements will be displayed in the form, drag-and-drop the elements or use the up and down arrows.
  • To delete an element, select it and click Delete.

To save your form, click Save.

To discard all changes and go back to the last-saved version of the form, click Revert.

To preview a form, click Preview. New service request forms are previewed with services currently in your catalog. Change request forms are previewed with a sample service.

When one or more organizations are assigned to the form, the preview is based on the first organization and the first user within that organization (alphabetically). When one or more users or groups are assigned to the form, the preview is based on the first user or group (alphabetically), and if the user is a member of an organization, the preview is also based on the user's first organization (alphabetically). For example, if you have assigned a form to two groups named "Dev" and "Test", you will preview request forms as a member of the group "Dev". When a service contains multiple components, the preview of the Component section of the form is based on the Form tab for the first component (alphabetically).

Editing a form's name, visibility and workflow

Selecting a form in the Form Library panel and clicking Edit allows you to:

  • change the form's name
  • specify what users and groups have access to the form. Note that you can't create multiple global Service forms for new requests.
  • associate a completion workflow with a service change request form

You can't change publishing options for the Default Service form for new requests; it's always set to Publish - Global.

Deleting forms

To delete a custom form, select it in the Form Library and click Delete.

You can't delete any of the default forms.

If you upgraded from version 5.2 or earlier and you delete a non-default component form, components of that type will then use the default component form of that type.

Form elements for new service requests

The following table provides details on all form elements that you can add to the Service form for new service requests.

Elements in the Form Designer Toolbox for New Service Requests

Standard

Header

Adds heading text to the form.

Text

Adds explanatory text to the form.

Input Text Field

Allows the requester to enter a value, such as a note or a password.

Important: If users will enter a password on the request form, enable Hide User Input. When Hide User Input is enabled:

  • Asterisks (*) are displayed for this field value in the Request Details dialog, emails, and landing pages.
  • The password is stored, encrypted, in the Commander database.
  • The plain-text password can be accessed through the approval workflow variable #{request.services[x].settings.inputField['field name']}. For example, if you set the Display Label for the Input Text Field to "Password", you would access the password in an approval workflow script with the variable #{request.services[1].settings.inputField['Password']}.
  • If a request containing a password is copied, the password is blanked out.

Dynamic List

Allows the requester to select options from one or more lists that are updated in real time. Items from an external source are retrieved using a script to populate the list items. The lists can be dependent on other form elements, so the selection of one form element can dictate the choices that are available for another list. For more information, see Adding dynamic lists to forms.

Required By

The date the requester requires the service.

In the Default Lead Time (in days) field, enter a number if you want a default Required By date to be displayed on the form. Users can adjust this date.

Service / Component Properties

Primary Owner

Allows the requester to specify a primary owner for the service, or, if you enable the Display Only option, simply displays the primary owner on the form.

Custom/Placement Attribute

Allows the requester to specify a value for a custom attribute or placement attribute. Select an attribute from the drop-down list. The (Placement) suffix distinguishes placement attributes from custom attributes.

You can click Create New Attribute to configure a new custom attribute or placement attribute. See Using Custom Attributes to Add Infrastructure Metadata or Configuring Attributes for Intelligent Placement for more information.

You can create relationships between custom attributes, so that the value selected for one attribute affects the selectable values for other attributes. See Creating relationships between custom attributes.

All custom attributes that are configured to be available for VMs and virtual services are available for services as well. Note that it's generally best practice not to include the same custom attribute on both the Service form and the blueprint form. If a custom attribute is included on both the Service form and the blueprint form, the Service form takes precedence.

Important: Don't include text-type custom cost attributes on the request form. Including a text-type custom cost attribute allows the requester to specify the cost of the service they are requesting. Rather, include list-type custom cost attributes, so that you can control the values that a requester can specify.

To ensure accurate cost calculations, don't include custom cost attributes on the Service form; include them only on the blueprint form.

Expiry Date

Allows the requester to specify the expiry date for the service.

Allow "Never Expires": Displays the Never Expires checkbox on the service request form.

Default lifespan (in days): Controls the default expiry date displayed on the form.

Maximum lifespan (in days): Limits the expiry date the user can specify. If you don't provide a maximum lifespan, the user can choose any expiry date.

Override Cost Period: Displays the estimated cost for the entire lifespan of a requested service, rather than for the cost period configured for the Estimated Cost element. When you enable this option, the Lifespan Cost is shown in the service catalog entry details, the shopping cart, the request form, and approval emails. For example, if you configure a default lifespan of 2 years (730 days), the service catalog entry details display the cost for 2 years. On the request form, if the user changes the default expiry date to three years, the three-year lifespan cost is shown.

When you enable this option, you must also enter a value for Default lifespan (in days).

When using lifespan cost, we recommend that you don't enable the Allow "Never Expires" option. If a user adds two services to the shopping cart and sets one to never expire but sets an expiry date for the other, the Estimated Cost label in the shopping cart may be confusing.

Lifespan Label: This label is displayed only in the service catalog entry details. If you enable Override Cost Period, it's a good idea to include the default lifespan in the Lifespan Label. For example, if you configure a default lifespan of two years (730 days), enter "Lifespan Cost for 2 Years" in the Lifespan Label field.

Quantity

Allows the requester to request multiple identical services more easily. Also allows you to limit the number of each service that can be requested.

Don't include the Quantity form element when Commander is in single-service request mode, because in this mode, Quantity simply displays "1" for a value, rather than allowing users to select a number.

Estimated Cost

Displays the estimated annual, quarterly or monthly cost for a VM or virtual service.

If the Override Cost Period option is enabled for the Expiry Date element, the Lifespan Cost is displayed on the form instead of the Estimated Cost.

Destination

Allows the requester to select from all deployment destinations available to this user and valid for the requested service.

Service Catalog costs are updated to reflect the selected destination, so that requesters can understand the cost impact of their decision.

If a user belongs to multiple groups, only the most specific assignment is used, with the following order of precedence:

  1. Destinations assigned directly to this user
  2. Destinations assigned to a group in which the user is a direct member
  3. Destinations assigned to a parent group (that is, a parent group of a group in which this user is a direct member)

This rule ensures that you can control what destinations users will see. For example, if a destination is assigned to a parent group, but not to a child group, a member of the child group will only see that destination if that user has no more specific assignments (numbers 1 and 2 in the order of precedence).

When a user selects Let the system decide and multiple destinations are available to the user for the selected service, the destination with the highest rating is displayed as the expected destination, right under the drop-down menu. If only one destination is available to the user, the control displays a read-only field instead of a drop-down menu. When no destinations are available to the user, Let the system decide is selected.

If you don't make this element mandatory, the default selection on the form is Let the system decide.

If you make this element mandatory, the option Let the system decide is removed from the list of selectable options for requesters, and you must choose from the following options:

  • Force Selection: The Destination menu is blank by default, so the user must select a destination.
  • Provide Default: The best-suited destination is preselected in the Destination menu, so the user can accept this default without making a selection.

If this element is non-mandatory and the user selects Let the system decide, Commander recalculates the target destination based on the user's storage tier and network zone selections on the component blueprint form.

If you add this element to the Service form and enable the Limit Selections option, the storage tiers and network zones configured for the selected deployment destination are shown on the form, rather than those you configured for the Storage element and the Network element. The Limit Selections option ensures that users don't select a storage tier or network zone that's unavailable on the target destination. The Storage element and the Network element appear on the blueprint form, which you configure in the Service Catalog.

A star rating is displayed for each valid destination for the requested service. Users can click an Information icon to understand how each destination is rated for quota, cost and preferred placement attribute values. A rating of 100 translates into a 5-star rating, a rating of 80 translates into a 4-star rating, and so on. See How Intelligent Placement Works to learn more.

Multi-Select

Allows the requester to select multiple values for a custom attribute. Use this form element to add any list-type custom attribute that's configured to apply only to forms.

This element works only with form attributes, so the values selected on the form are not applied as metadata on deployed services. Therefore, you should use this element only when you need users to be able to multi-select values on the form, but you don't need the metadata to be applied on deployed services. Use the regular Custom/Placement Attribute form element for metadata that persists on deployed services.

You can click Create New Attribute to configure a new custom attribute. See Creating custom attributes for more information.

To allow users to multi-select values, enable Select Multiple.

Form elements for service change requests

The following table provides details on all form elements that you can add to service change request forms.

Elements in the Form Designer Toolbox for Change Requests

Standard

Header

Adds heading text to the form.

Text

Adds explanatory text to the form.

Input Text Field

Allows the requester to enter a value, such as a note or a password.

Important: If users will enter a password on the request form, enable Hide User Input. When Hide User Input is enabled:

  • Asterisks (*) are displayed for this field value in the Request Details dialog, emails, and landing pages.
  • The password is stored, encrypted, in the Commander database.
  • The plain-text password can be accessed through the approval workflow variable #{request.services[x].settings.inputField['field name']}. For example, if you set the Display Label for the Input Text Field to "Password", you would access the password in an approval workflow script with the variable #{request.services[1].settings.inputField['Password']}.
  • If a request containing a password is copied, the password is blanked out.

Dynamic List

Allows the requester to select options from one or more lists that are updated in real time. Items from an external source are retrieved using a script to populate the list items. The lists can be dependent on other form elements, so the selection of one form element can dictate the choices that are available for another list. For more information, see Adding dynamic lists to forms.

Required By

The date the requester requires the service.

In the Default Lead Time (in days) field, you can enter a number if you want a default Required By date to be displayed on the form. Users can adjust this date.

File Upload

Allows the requester to upload files during the service request process. Uploaded files are added to the VM's local directory as configured in the completion workflow using the Copy Uploaded File workflow step.

Service / Component Properties

Primary Owner

Allows the requester to specify a primary owner for the service / component, or, if you enable the Display Only option, simply displays the primary owner on the form. Not available for forms targeting managed systems.

Select one of the following allowed actions:

  • Add as new Primary Owner
  • Replace existing Primary Owner
  • Replace all existing owners

Organization

Allows the requester to assign the component to another organization example, to free up quota, or to transfer a VM from the testing organization to the development organization as part of bug detection and resolution. Not available for forms targeting managed systems.

In the Visibility drop-down list, select one of the following to control which organizations the requester can select:

  • All Organizations
  • Requester's Organizations
  • Custom list - select one or more organizations from the list

To ensure that the service is visible to the primary owner, the primary owner must be a member of the selected organization. If the primary owner is not a member of the selected organization, the error "Primary owner is not a member of the selected organization" error appears in approval emails, approval landing pages, and the Request Details dialog. When manually approving requests, approvers can use the $ORGANIZATION deployment parameter to assign an organization. If multiple organizations are available, approvers can also use the Organization drop-down list on the approval landing page. Administrators can also change the target organization in the Fulfill Request dialog.

Custom/Placement Attribute

Allows the requester to specify a value for a custom attribute or placement attribute. Select an attribute from the drop-down list. The (Placement) suffix is used to distinguish placement attributes from custom attributes.

You can click Create New Attribute to configure a new custom attribute or placement attribute. See Using Custom Attributes to Add Infrastructure Metadata or Configuring Attributes for Intelligent Placement for more information.

You can create relationships between custom attributes, so that the value selected for one attribute affects the selectable values for other attributes. See Creating relationships between custom attributes.

Expiry Date

Allows the requester to extend the expiry date of a service. Not available for forms targeting managed systems.

Another way to allow VM expiry extension is through the Expiry Extension setting in the Expiry policy.

Allow "Never Expires": Display the Never Expires checkbox on the service request form.

Component Name

Allows the requester to change the display name of a VM component. See also Order of precedence for deployed service names. Not available for forms targeting managed systems.

Schedule

Allows the requester to specify when a change request will be fulfilled. All parts of a change request are fulfilled at the same time. The Schedule form element takes precedence over the automation options in the approval workflow.

Select one or more allowed options from the drop-down menu:

  • Immediately: Changes are fulfilled immediately after approval.
  • In Maintenance Window: Changes are fulfilled during the next maintenance window.

If the approval process is not complete before the next maintenance window begins, the changes are automatically rescheduled for the next maintenance window.

Specific Time: Changes are fulfilled at the specified time.

If the approval process is not complete before the specified time, the changes won't be fulfilled. The request state will be "Failed", and a comment will appear in the Request Details in red, indicating that the request was not fulfilled. An administrator must manually fulfill the request in this case.

After the request is approved, a scheduled task is created. The requester will be able to see and delete this scheduled task if necessary.

Resources (not available for forms targeting managed systems)

Instance Type

Allows the requester to change the resources for a public cloud instance. The requester can select only instance types that are compatible with the current instance type.

For EC2 instances, the requester can also set the EBS Optimized option on the form if the selected instance type supports it.

If you're managing GCP instances, the option Allow Custom CPU/Memory for GCP Instances is displayed for this form element. GCP allows users to choose both predefined and custom instance types. When you enable this option, you can use the CPU Count and Max Memory Size options to limit the number of CPUs and the amount of memory users can request. Note that Commander doesn't validate the values you enter for CPU Count or Max Memory Size. The maximum number of CPUs allowed for GCP custom machine types is 96. The memory for a GCP custom machine type must be a multiple of 256 MB, and must be between 0.9 and 6.5 GB per vCPU (unless Extended Memory is enabled; note that Extended Memory incurs additional charges). If you don't enable the Allow Custom CPU/Memory for GCP Instances option, users can only request a predefined instance type, even for instances that currently have a custom machine type. Therefore, if you allow custom machine types in your environment, we recommend enabling this option to prevent confusion.

CPU Count

Allows the requester to specify CPU requirements for a VM component. You can limit the number of CPUs that users can request by entering a comma-separated list of values (for example, 1,2,4).

This element is not displayed on public cloud VM component forms.

Memory

Allows the requester to specify memory requirements for a VM component. You can limit the amount of memory that users can request.

This element is not displayed on public cloud VM component forms.

Storage

Allows the requester to specify storage requirements for a VM or virtual service component on vCenter or SCVMM. The selectable storage tier values can be customized.

You must ensure that datastores are available to back all storage tiers in use.

It's not possible to resize IDE disks, independent disks, or disks involved in a snapshot or linked clone chain.

Allowed Actions: Specify whether the requester can Add disks, Change disks, and Remove disks.

If you specify that the user can change existing disks, specify the Maximum Disk Size.

If you specify that the user can both add and change disks, specify the Maximum Disk Size and Maximum Extra Disks.

Storage - AWS

Allows the requester to change storage requirements for an Amazon EC2 instance.

Selectable Disk Types:

  • General Purpose (SSD): General purpose Solid-State Drive volume that balances price and performance for a wide variety of transactional workloads. Recommended for system boot volumes, virtual desktops, low-latency interactive apps, development and test environments.
  • Provisioned IOPS (SSD): Highest-performance SSD volume designed for mission-critical applications. Best for critical business applications that require sustained IOPS performance, or more than 10,000 IOPS or 160 MiB/s of throughput per volume, such as large database workloads and EBS-optimized instances. The ratio of IOPS provisioned and the volume size requested can be a maximum of 50.
  • Magnetic: Previous-generation Hard Disk Drive volumes for workloads where data is infrequently accessed. Not recommended for new applications.
  • Throughput Optimized (HDD): Low-cost Hard Disk Drive volume designed for frequently accessed, throughput-intensive workloads. Best for streaming workloads requiring consistent, fast throughput at a low price, such as big data, data warehouses, and log processing. The minimum disk size for this type is 500 GB. can't be a boot volume.
  • Cold (HDD): Lowest-cost Hard Disk Drive volume designed for less frequently accessed workloads. Best for throughput-oriented storage for large amounts of data that's infrequently accessed. The minimum disk size for this type is 500 GB. can't be a boot volume.

Allowed Actions: Specify whether the requester can Add disks, Change disks, and Remove disks.

If you specify that the user can add disks:

  • specify the Maximum Disk Size and Maximum Extra Disks
  • specify whether new disks will be encrypted by default with the Encryption option
  • specify whether new disks will be deleted on termination by default with the Delete on Termination option

If you specify that the user can change disks:

  • specify the Maximum Disk Size
  • specify whether new disks will be encrypted by default with the Encryption option
  • specify whether new disks will be deleted on termination by default with the Delete on Termination option

Storage - Azure

Allows the requester to change storage requirements for an Azure VM.

Storage Types: Select Managed and/or Unmanaged as required.

Selectable Disk Types: If you selected Managed in the Storage Types list, you can select one or both of the following disk types:

  • SSD: Premium disks (SSD) are backed by solid-state drives and offer consistent, low-latency performance. They provide the best balance between price and performance, and are ideal for I/O-intensive applications and production workloads. Premium disks are not supported for all instance types.
  • HDD: Standard disks (HDD) are backed by magnetic drives and are preferable for applications where data is accessed infrequently.

Display Storage Tier: If you selected Unmanaged in the Storage Types list, you can specify whether the user can select a storage tier.

Selectable Tiers: If you selected Unmanaged in the Storage Types list, and you enabled Display Storage Tier, select storage tiers to make them available on the form.

Allowed Actions: Specify whether the requester can Add disks, Change disks, and Remove disks.

If you specify that the user can add disks, specify the Maximum Disk Size and Maximum Extra Disks.

If you specify that the user can change disks, specify the Maximum Disk Size.

Commander chooses the datastore for new unmanaged disks using the following order of precedence:

  • All disks in the target region with the requested storage tier are sorted alphabetically. If there are no matches, the task fails.
  • Next, for any of the deployment destinations that target the VM's resource group, Commander searches for datastores targeted by those deployment destinations, and chooses the first alphabetically.
  • Next, for any of the deployment destinations that are assigned to the user and/or the user's organization, Commander searches for datastores targeted by those deployment destinations, and chooses the first alphabetically.
  • Next, Commander searches for datastores belonging to the VM's resource group, and chooses the first alphabetically.
  • If none of these criteria generates a match, the task fails.

Estimated Cost

Displays the estimated annual, quarterly or monthly cost for a service.

Adding dynamic lists to forms

The Dynamic List form element runs a script to retrieve items from an external source to populate the form list at request time. The scripts, which can be written in the language of your choice, can use values of other form elements to build dynamic lists of values with relevant content. Using variables, the scripts can access additional information such as the requester's user name or email address. They can be added to a change request form, service form, or service component form.

Dynamic drop-down lists allow you to maintain real-time values for any frequently changing form options. Using any external system’s API, dynamic lists can retrieve lists such as:

  • available organizations to join
  • cost centers that are accessible to a user
  • database types and the appropriate versions for each database type
  • all subnets in the destination selected on the form

Using Commander variables in dynamic list scripts

Some Commander variables can reference other form elements and some Commander variables can reference other information. See Script examples for the Dynamic List form element.

  • The maximum length of variable values is 1000 characters.
  • Dynamic list variables can't have costs associated with them.

The script won't execute until all variables have a value. If the form contains a blank list, the issue might be that one or more variables aren't resolving. To fix this issue, check the Commander log file for the following message: Dynamic list [name] can't resolve variables: [variable names], and provide access to the missing variables.

Access through:

Configuration > Self-Service

Available to:

Commander Roles of Superuser and Enterprise Admin

To configure a script for the Dynamic List form element:

  1. Click the Forms tab.
  2. In the Toolbox of the Form Designer, click Dynamic List.
  3. In the Dynamic List form element, click the Configure link to edit and test the script before publishing it.
  4. Dynamica List Form Element

  5. In the Edit Script dialog, optionally enter any arguments that you want to pass to the script executable in the Script Arguments field.

    Click vars-20x20 to open the Variable Assistant dialog, which allows you to select variables for the current context and provides help for each variable. See Variable Syntax for Emails and Scripts. Maximum length is 2048 characters.

  6. Dynamic List Edit Script

  7. In the Script field, enter the script to be executed.

    Click vars-20x20 to open the Variable Assistant dialog, which allows you to select variables for the current context and provides help for each variable. See Variable Syntax for Emails and Scripts. The result must be a JSON string array.

  8. In the Executable field, enter the executable that will be used run the script.

    If your system environment doesn't have the script executable on its path, you must provide the fully qualified path to it (for example, C:\python37\python.exe). To use PowerShell, you only need to enter powershell.exe.

    Some scripting executables require files to have a particular extension (for example, powershell.exe requires a .ps1 extension for scripts). For an executable that requires a file extension, you must map the executable and file extension in the advanced system property embotics.workflow.embedded.script.extensions. By default, mappings already exist for the following executables: powershell.exe=.ps1, python.exe=.py, cmd.exe=.bat. See Setting system properties in Commander for details on how to modify system properties through Commander.

  9. In the optional Credentials field, select or add guest OS credentials that are required to run the script. See Managing Credentials.

    The credential contents are populated into environment variables that the script can access.

  10. In the Timeout field, adjust the default timeout, if required. The script will fail if it can't be completed within the given time. Maximum timeout is 99 seconds.
  11. In the optional Fallback Value field, enter a value that will be used if the script fails or times out.
  12. Optional: Test your script. See Testing dynamic list scripts.

    The script output has a maximum limit as defined in the advanced system property embotics.execute.command.task.capture.length, which is 512 KB by default.

  13. Click OK.

Notes:

  • If some lists contain content that's dependent on the selections made in other form elements, arrange the lists so they appear in the form in the order of their dependence, top to bottom. When requesters work from top to bottom on the form, their choices may affect the contents of subsequent lists. If requesters go back and make changes, they may lose some of their selections.
  • You can't create two lists that reference each other.

Testing dynamic list scripts

Use the Test tab of the Edit Script dialog to see the output of your script. If your script contains Commander variables, you can specify the values of each variable in the script and view the results. If there are no variables in your script, the Variable/Value section won't appear in the Test tab of the Edit Script dialog. See Script examples for the Dynamic List form element.

Script status is recorded in the Commander log file. A successful script exit code is 0. Any other exit code means that the script has failed. Details of script failures are displayed in the Test tab result field.

If the script fails during deployment, users will see a generic failure alert, but details of the failure won't be exposed to users. Users will be directed to contact their administrator.

Script examples for the Dynamic List form element

Here are two examples that illustrate how to use dynamic lists.

Example 1: List that depends on another list

The following script retrieves a list of Canadian provinces. The results will be used in the second list. Both dynamic list elements are added in sequence to the form.

$headers = @{Accept = "application/json" }
  $Data = Invoke-RestMethod -Method Get -Uri "http://geogratis.gc.ca/services/geoname/en/codes/province" -Headers $headers
  ($Data.definitions)|Select -ExpandProperty description | ConvertTo-Json

Dynamic List Edit Script Provinces

Running this script in the Test tab shows the list of provinces that will be visible to users.

Dynamic List Test Script Provinces

This script below retrieves the selected province from the list above and inserts it into the variable service.settings.dynamicList['Province']. This script is added to a new Dynamic List form element. From this information, the script produces a list of cities that are relevant to that province.

$headers = @{Accept = "application/json" }	
$Data = Invoke-RestMethod -Method Get -Uri "http://geogratis.gc.ca/services/geoname/en/codes/province" -Headers $headers
$Provinceid = $Data.definitions | Where-Object {$_.description -eq "#{service.settings.dynamicList['Province']}"} | Select-object code -ExpandProperty code
$CityData = Invoke-RestMethod -Method Get -Uri "http://geogratis.gc.ca/services/geoname/en/geonames?province=$Provinceid&concise=CITY" -Headers $headers

$result = @()

if ($CityData.items.Length > 1) {
   $result += $CityData.items |Select -ExpandProperty name 
} else {
   $result = $CityData.items |Select -ExpandProperty name
}

ConvertTo-Json @($result)

Dynamic List Edit Script Cities

Dynamic List Variable Assistant

Running this script in the Test tab shows the list of cities that will be visible to users after they have selected the province Ontario. Using this Test tab, you can change the value of the variables in the script, run the script, and see the appropriate output.

Dynamic List Test Script Cities

In the Service Catalog, the two lists will be available for selection; a list of provinces and a list of cities for the province that was selected in the first list.

Dynamic List Test New Service Request Form

Example 2: List that includes credentials to an API request using environment variables

This is an example of how a script that can be used for a dynamic list form element can retrieve the username and password from the credentials. The credentials selected in the Edit Script dialog are injected into the script's environment variables. This sample script accesses Commander metadata to get a list of services.

$user = (Get-Item Env:SELECTED_CREDENTIALS_USERNAME).value;
$pass= (Get-Item Env:SELECTED_CREDENTIALS_PASSWORD).value;
$secpasswd = ConvertTo-SecureString $pass -AsPlainText -Force
$cred = New-Object System.Management.Automation.PSCredential($user, $secpasswd)
$headers = @{Accept = "application/json" }
$Data = Invoke-RestMethod -Method Get -cred $cred -Uri "https://#{system.address}:#{system.port}/rest/v3/services" -Headers $headers
$Data.items |Select -ExpandProperty name | ConvertTo-Json