{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":29225,"path":"it-operations-management/cloud-configuration-governance/expressions-cloud-mgt.md","title":"Using expressions in Cloud Provisioning and Governance","bundle":null,"doc_type":null,"release":"australia","body":"\n# Using expressions in Cloud Provisioning and Governance\n\nExpressions in policy actions can set or override values. Expressions in blueprints can access attributes of resources and can map values to request form fields. Expressions are available in resource blocks, blueprints, policies, and anywhere that Cloud Provisioning and Governance allows scripts.\n\n## Using expressions\n\nExpressions can hold the values for information that is dynamically generated in the system, such as the values for the selections users make on the Cloud User Portal. Expressions are available in resource blocks, blueprints, policies, and anywhere that Cloud Provisioning and Governance allows scripts.\n\n- **Using expressions in resource blocks**\n\n Each resource block operation uses an expression to hold a value for each parameter. The expression can use hard-coded values, data from the stack that the user provisions in the Cloud User Portal, data in the CMDB, and data that is derived from scripts. By default, Cloud Provisioning and Governance generates a set of parameters and their expressions for each resource block operation.\n\n For example, the parameter **Location**, which holds the datacenter that a resource belongs to, uses the expression `${parameter.Location}`\n\n \\[Omitted image \"parameters-for-resource-blocks.png\"\\] Alt text: Location parameter for a resource block\n\n- **Using expressions in blueprints**\n\n Blueprints can use expressions to map input parameters for each operation on a resource block. By default, the blueprint displays the same parameters and values that are specified in the resource block.\n\n You can access blueprint attributes with expressions. The expression in the **Mapping** column defines blueprint attributes for each operation in a step. For example, the **Location** attribute, which appears on the stack request form, is accessible through the `{$parameter.Location}` expression. The Location parameter with the `${parameter.Location}` value appears on the **Inputs** tab when you select a blueprint operation.\n\n \\[Omitted image \"rb-operation-parameter.png\"\\] Alt text: The Location parameter and expression\n\n- **Using expressions in policy actions**\n\n Policy actions can use expressions to override parameter values that users submit in a request form on the Cloud User Portal. You can also access and override user data in stack operations. For example, use the following expression to rename a stack: `formData.Stackname = \"your-naming-convention\";`.\n\n \\[Omitted image \"policy-script-example.png\"\\] Alt text: Policy example script\n\n\nYou can access blueprint attributes with expressions. The expression in the **Mapping** column defines blueprint attributes for each operation in a step. For example, the **Location** attribute, which appears on the request form for a virtual machine, is accessed in the following expression: `{$parameter.Location}`.\n\n## Expression types\n\n- **Definitional expressions**\n\n Definitional expressions are a form of early binding \\(or static binding\\). These bindings refer to compile-time binding and are evaluated when the user submits the stack request form \\(when stack or resource provisioning starts\\). Definitional expressions do not have access to the data that is generated during Orchestration. Definitional expressions are enclosed in curly braces. For example: `${parameter.CloudAccount}`\n\n- **Runtime expressions**\n\n Runtime expressions are a form of late binding \\(or dynamic binding\\). These bindings refer to runtime binding and have access to the data that is created during Orchestration \\(for example, stack items\\). Runtime expressions are evaluated when called during an Orchestration run. Runtime expressions are typically used for dot-walking to data in tables. Runtime expressions are enclosed in parentheses. For example: `$(Stack.items[VM1].attributes[node_id])`\n\n- **Definitional/Runtime expressions**\n\n Some expressions include both definitional and runtime expressions.\n\n- **Complex expressions**\n\n You can nest expressions of any type within other expressions.\n\n\n## Definition expression syntax and examples\n\nAllowable syntax uses a dollar sign and curly braces. These types are available:\n\n- `${parameter.}`. Use this kind of expression to retrieve values from input attributes of processes like blueprint provisions. Data is not fetched from tables.\n- `${Stack.items[]}`. Use this syntax to access attributes of specific items in a stack.\n- `${randomNumber}`. Use this syntax to generate a random number. For example, you can provision a VM with a random node name or stack name.\n\n|Example|Description|\n|-------|-----------|\n|$\\{parameter.BillingCode\\}|This expression shows how a billing code parameter appears in a blueprint.|\n|$\\{parameter.formData.CatalogAttributeType\\}|This expression takes a catalog attribute that is submitted by a user while the user fills out the form for a catalog item in the Cloud User Portal.|\n|$\\{parameter.userData.userId\\}|This expression takes the ID of a user while the user fills out the form for a catalog item in the Cloud User Portal.|\n|$\\{Stack.items\\[Virtual Server\\].attributes\\[sys\\_id\\]\\}|This expression gets the sys\\_id of a virtual server that is apart of a stack. Virtual Server is the alias of a resource block used in the stack.|\n\n## Runtime expression syntax and examples\n\nAllowable syntax uses a dollar sign and parenthesis. These types are available:\n\n- `$(ci.tablename)` where `tablename` is a table in the system, usually a CI table in the CMDB. Use this syntax to access values of fields in the table.\n- `$(Stack.items[])`. Use this syntax to access attributes of specific items in a stack.\n\n|Example|Description|\n|-------|-----------|\n|`$(ci.cmdb_ci_cloud_subnet[ sys_id=12231231231231231231].cidr)`|This expression dot walks to the Cloud Subnet table, finds the specific record with the given sys\\_id, and takes the value from the `cidr` column.|\n|`$(ci.sn_cmp _ip_pool[subnet=${parameter.formData.Subnet Id}])`|This expression combines runtime and definition type expressions. The equal sign = is used to evaluate a value for a match. The expression dot-walks to the IP Pool table and looks for the subnet that has the subnet ID that the user submitted.|\n|`$(ci.cmdb_ci_cloud_subnet[${parameter.formData.SubnetId}].cidr)`|This expression combines runtime and definition type expressions. The expression takes the value of the **cidr** field from a subnet that the user chose during provisioning. The square brackets `[]` indicate that the expression dot-walks to the Cloud Subnet table and then looks at the subnet value that the user submitted on a blueprint provision. The expression grabs the **cidr** field value and then walks to the value in the **cidr** field of the sys\\_id of the subnet.|\n|$\\(Stack.items\\[Virtual Server\\].attributes\\[sys\\_id\\]\\)|As in the definition expression example, this expression takes the sys\\_id of a virtual server that is apart of a stack.|\n\n## Example expression\n\n`$(ci.cmdb_ci_nic[$(Script:CMPVMNICs.getNICs[arg=$(Stack.items[Virtual Server].attributes[sys_id])])].private_ip)`\n\n- **$\\(ci**: Runtime expression to retrieve data from table.\n- **cmdb\\_ci\\_nic**: CI for NIC \\(Network Interface Card\\).\n- **$\\(Script**: Script-based expression.\n- **CMPVMNICs**: Script include.\n- **getNICs**: Function inside a script include.\n- **arg**: Arguments to script include function. Arguments are separated by \",\" when there are multiple attributes.\n- **$\\(Stack.items**: Runtime stack expression to retrieve stack item from a stack. Argument is the alias specified in blueprint.\n- **Virtual Server**: Alias of resource used in blueprint.\n- **$\\(Stack.items\\[Virtual Server\\].attributes\\[sys\\_id\\]\\)**: Retrieve sys\\_id of stack item \\(\"Virtual Server\"\\) resource instance in a stack.\n- **private\\_ip**: Attribute from cmdb\\_ci\\_nic. Replace with public IP if required.\n\n## Expressions\n\n\n
\n\n**Simple parameter mapping expression**\n\n This type of expression retrieves values from input attributes of processes, such as blueprint operations, resource blocks, and policies. Data is not fetched from tables. Maps values from one layer to another, such as from a Blueprint to a Resource to the Cloud API.\n\n - Type: definitional\n- Syntax: `${parameter.}`\n- Examples:\n - `${parameter.BillingCode}` returns the billing code.\n - `${parameter.formData.CatalogAttributeType}` takes a catalog attribute that is submitted on the request form in the Cloud User Portal.\n - `${parameter.userData.userId}` takes the ID of a user working on the request form in the Cloud User Portal.\n\n
\n\n**Stack item expression**\n\n A CI instance in the CMDB represents each stack item. Use Stack Item expressions to look up first-level properties on the CI that back the stack item or on the stack item itself.\n\n - Type: definitional/runtime\n- Syntax: `${Stack.items[]}` or `$(Stack.items[])`\n- Examples:\n\n`${Stack.items[VirtualServer1].attributes[sys_id]}` is a definitional type expression that gets the sys\\_id of a virtual server in a stack. `VirtualServer1` is the alias of a resource block that is used in the stack.\n\n`$(Stack.items[VirtualServer2].attributes[sys_id])` is a runtime type expression that takes the sys\\_id of a virtual server that is a part of a stack.\n\n`${Stack.items[vm1].attributes[node_id]}` reads the `node_id` attribute of the CI that was created for the VM. `vm1` is the stack item name \\(or the alias of the resource in the blueprint\\).\n\n`$(Stack.items[vm1].status)` reads the status of the stack item.\n\n\n
\n\n**Property override expressions in policies**\n\n In policies, you can override properties by pulling a value from the system or by using a random number. You can use data from both the forms in the Cloud User Portal and from the user who performed the operation on the form.\n\n - Type: definitional/runtime\n- Syntax: `${parameter.formData.xyz}` or `${this.parameter.userData.xyz}`\n- Examples:\n\nThe following value can set the stack name to **Stack\\_Bob.Smith@company.com**: `Stack_${parameter.userData.userId}`\n\nSet stack or table values using runtime expressions by taking the subnet from the IP Pools table:\n\n`$(ci.sn_cmp _ip_pool[subnet=${parameter.formData.Subnet Id}])`\n\nIn scripts, you can assign values as follows:\n\n`formData.App_Server_NodeName = \"MyNodeName\";`\n\n`this.parameter.userData.userId == 'servicenowuserId';`\n\n- See also [Create a policy action script]().\n\n
\n\n**Script expression**\n\n In the example, `VMProperties` is a script include with a function called `getIP`. A script expression is also an example of a complex expression \\(the expression is nested\\).\n\n - Type: runtime\n- Syntax: `$(Script:scriptName.function[])`\n- Examples:\n\n`$(Script:VMPropertiesUtil.getIP[ arg=$(Stack.items[VM1].attributes[object_id])])`\n\nExpression for Private IP:`$(ci.cmdb_ci_nic[$(Script:CMPVMNICs.getNICs[arg=$(Stack.items[Virtual Server].attributes[sys_id])])].private_ip)`\n\nExpression for Public IP: `$(ci.cmdb_ci_nic[$(Script:CMPVMNICs.getNICs[arg=$(Stack.items[Virtual Server].attributes[sys_id])])].public_ip)`\n\nExpression to get the credential alias: `$(Script:CMPVMUtils.getCredentialAlias[arg=${Stack.items[Virtual Server].attributes[sys_id]}])`\n\nExpression to get the IP address: `$(Script:CMPVMUtils.getReachableIp[arg=$(Stack.items[Virtual Server].attributes[sys_id])])`\n\n\n
\n\n**CI lookup expression**\n\n Accesses values of fields in a table, usually a CI table in the CMDB.\n\n - Type: definitional/runtime\n- Syntax: `$(ci.tableName)`\n- Examples:\n\n`$(ci.sn_cmp _ip_pool[subnet=${parameter.formData.Subnet Id}])` combines runtime and definition type expressions. The = operator evaluates a value for a match. The expression dot-walks to the IP Pool table and looks for the subnet that has the subnet ID that the user submitted.\n\n`$(ci.cmdb_ci_cloud_subnet[${parameter.formData.SubnetId}].cidr)` takes the value of the `cidr` field from a subnet that the user specified during provisioning. The expression dot-walks to the Cloud Subnet table, looks at the subnet value that the user submitted on a blueprint provision, extracts the `cidr` field value, and then walks to the value in the `cidr` field of the sys\\_id of the subnet.\n\n\n
\n\n**Random number expression**\n\n Generates a random number. For example, you can provision a VM with a random node name or stack name.\n\n - Type: runtime\n- Syntax and example: `${randomNumber}`\n\n
\n\n**Scratchpad expression/Resource operation output attribute expression**\n\n Reads output attributes from one operation into another operation.\n\n - Type: runtime\n- Syntax: varies\n- Example: To set/expose outputs from one operation:\n\n`${Compute Interface.CreateNode.Output.resp.nodeId}`\n\nTo read the output attributes \\(where `VM1.Provision` is the operation whose output attributes are read\\):\n\n`$(Outputs[VM1.Provision].NodeId)`\n\n\n
\n\n**Conditions in expressions**\n\n You can use conditional expressions in blueprint steps and resource operation steps to conditionally execute or skip the step. The conditional expressions are Javascript expressions and they support expression substitutions.\n\n - Type: definitional/runtime\n- Syntax: varies\n- Examples:\n\n‘$\\{parameter.CloudAccount\\}’==’Amazon Cloud Account’\n\n‘$\\(Stack.items\\[vm1\\].attributes\\[node\\_id\\]\\) ’== ’VM1’\n\n\n
\n\n**Complex expression**\n\n You can nest expressions. In the example, `${parameter.ServerID}` maps the sys\\_id of the CI and is replaced before the outer expression is consumed.\n\n - Type: any\n- Syntax: varies\n- Example: `$(ci.cmdb_ci_vm_instance[${parameter.ServerID}].name)`\n\n
\n\n**Order context**\n\n This expression is useful for life cycle operations and enables you to dot-walk on the order attributes as part of the **sn\\_cmp\\_order** table.\n\n - Type: runtime\n- Syntax: `$(context.order.column_name)`\n- Examples:\n - Request Item: `$(context.order.sc_req_item)`\n - Dot-walk on request item object: `$(context.order.sc_req_item.number)`\n - Mixed Expression \\(Constant + Expression\\): `\"ram$(context.order.sc_req_item.number)\"`\n\n
"}}