Special Field Types

Introduction

Universal Extensions consist of two primary parts:

  1. A Universal Template definition that is created and stored in the Controller.

  2. A Python zip archive that is developed outside the Controller and contains Python source code that implements the Extension functionality. 

The Universal Template essentially defines the User interface for a Universal Task. That includes the fields that supply data for a task

The Universal Template supports the following field types:

  • Text

  • Integer

  • Float

  • Boolean

  • Array

  • Choice

  • Script

  • Credential

  • SAP Connection

  • Database (DB) Connection

During task execution, fields are passed to the extension_start method of the Python script that implements the logic of the Extension via the fields parameter. The fields parameter is a dictionary populated with field values from the associated task instance that was launched in the Controller.  The keys of the dictionary correlate with field names of the task instance that is invoking the extension (defined in the associated Universal Template) and the key values are the values from the associated form fields when the task is launched.

The following sections describe how field values of each field type represented in Python when passed to the Extension instance in the fields dict.

Text Type Field

Fields defined in a Universal Template as type Text will have a value of type str in the fields dict. The value will be the contents of the form field from the Controller.

Integer Type Field

Fields defined in a Universal Template as type Integer will have a value of type int in the fields dict. The value will be the integer representation of the form field from the Controller.

Float Type Field

Fields defined in a Universal Template as type Float will have a value of type float in the fields dict. The value will be the floating-point representation of the form field from the Controller.

Boolean Type Field

Fields defined in a Universal Template as type Boolean will have a value of type bool in the fields dict. The value will be the boolean representation of the form field from the Controller (i.e., True or False).

Array Type Field

Fields defined in a Universal Template as type Array will have a value of type list in the fields dict. Each element of the list will be populated with a dict that represents the array element from the Controller. The dict representing the array element will contain a key value pair where the key corresponds to the element Name in the Controller and value corresponds to the element Value in the Controller. The “value” portion of the element will be of type str. For example:

{
  "array_1": [
    { "My_element_1": "Value 1" },
    { "My_element_2": "Value 2" }
  ]
}

Code Example

# Get and print array_1
print('Array 1:')
array_1 = fields.get("array_1", [])
# The array is stored as a list of dicts - each containing a 
# single key/value pair indicating the 'name' and 'value' for 
# the given array element.
for row_dict in array_1:
    for k,v in row_dict.items():
        # Print the array element 'name' and 'value'.
        print('{0}\t{1}'.format(k,v))

Choice Type Field

Fields defined in a Universal Template as type Choice will have a value of type list in the fields dict. The elements of the list will be the values associated with the selected “choices” in the associated task instance. The values will be of type str. For example:

{
  "choice_1": [ "choice value" ]
}

Code Example

# Get the value of the 'choice_1' field
choice_value = fields.get('choice_1', [""])[0]

Script Type Field

Fields defined in a Universal Template as type Script will have a value of type str in the fields dict. At execution time, UAG will write the Data Script associated with the Script type field to the file system. The path to that Data Script file on the local file system is what is passed in the field value. For example:

'C:\\Program Files\Universal\tmp\97eb9821-d3fc-43b8-b355-abf6979d7286.'

Credential Type Field

Fields defined in a Universal Template as type Credential will have a value of type dict. The dict representing the credential will contain key value pairs for the following keys:

  • user

  • password

  • keyLocation

  • passphrase

  • token

For example:

{
  "credential_1": {
    "user": "value",
    "password": "value",
    "keyLocation": "value"
    "passphrase": "value",
    "token": "value",
  }
}

Code Example

The Credential values in the fields dict can be referenced as follows:

user = fields[“credential_1"]["user"]
password = fields["credential_1"]["password"]

Key to Field Mapping

The key value pairs in the Credential dict represent the similarly named fields that make up a Credential definition in the Controller. Below is a mapping of dict key name to Credential field name in the Controller.

dict Key

Field Name

user

Runtime User

password

Runtime Password

keyLocation

Key Location

passphrase

Passphrase

token

Token

The value portion of the key value pair will be of type str and contain the corresponding value from the resolvable credential selected for the field in the Controller.

SAP Connection Type Field

Fields defined in a Universal Template as type SAP Connection will be passed to the extension instance as a value of type dict. The dict representing the SAP Connection will contain a collection of key value pairs that represent a set of fields from an SAP Connection defined in the Controller. The specific collection of fields represented in the dict will be dependent upon the "Connection Type" of the SAP Connection being referenced by the field (i.e., "Specific Application Server" or "Load Balancing").

Specific Application Server

A “Specific Application Server” connection type will have the following collection of keys:

{
  "sap_connection": {
    "name": "ABC - XBP 3.0 with Business Warehouse",
    "description": "ABC Test System",
    "sap_connection_type": "Specific Application Server",
    "sap_client": "800",
    "sap_ashost": "my-sapsys",
    "sap_sysnr": "45",
    "sap_gwhost": "",
    "sap_gwserv": "",
    "sap_mysapsso2": "",
    "sap_x509cert": "",
    "sap_saprouter": "",
    "sap_snc_mode": ""
    "sap_snc_lib": "",
    "sap_snc_myname": "",
    "sap_snc_partnername": "",
    "sap_snc_qop": "",
    "sap_snc_sso": ""
  }
}

Load Balancing

A “Load Balancing” connection type will have the following collection of keys:

{
  "sap_connection": {
    "name": "ABC - XBP 3.0 with Business Warehouse",
    "description": "ABC Test System",
    "sap_connection_type": "Specific Application Server",
    "sap_client": "800",
    "sap_mshost": "abcmain",
    "sap_r3name": "ABC",
    "sap_group": "PUBLIC",
    "sap_use_symbolic_names": "",
    "sap_mysapsso2": "",
    "sap_x509cert": "",
    "sap_saprouter": "",
    "sap_snc_mode": ""
    "sap_snc_lib": "",
    "sap_snc_myname": "",
    "sap_snc_partnername": "",
    "sap_snc_qop": "",
    "sap_snc_sso": ""
  }
}

Code Example

The SAP Connection values in the fields dict can be referenced as follows:

ashost = fields[“sap_connection"]["sap_ashost"]
sysnr = fields["sap_connection"]["sap_sysnr"]
client = fields[“sap_connection"]["sap_client"]

Key to Field Mapping

The key value pairs in the SAP Connection dict represent the similarly named fields that make up an SAP Connection definition in the Controller. Below is a mapping of dict key name to SAP Connection field name in the Controller.

dict Key

Field Name

Connection Type

name

Name

All

description

Description

All

sap_connection_type

Connection Type

All

sap_client

Client

All

sap_ashost

Application Server

Specific Application Server

sap_sysnr

System Number

Specific Application Server

sap_gwhost

Gateway

Specific Application Server

sap_gwserv

Gateway Service

Specific Application Server

sap_mshost

Message Server

Load Balancing

sap_r3name

System ID

Load Balancing

sap_group

Group

Load Balancing

sap_use_symbolic_names

Use Symbolic Names

Load Balancing

sap_mysapsso2

Single Sign-On Ticket

All

sap_x509cert

X.509 Certificate

All

sap_saprouter

SAProuter

All

sap_snc_mode

SNC Mode

All

sap_snc_lib

SNC Library

All

sap_snc_myname

SNC My Name

All

sap_snc_partnername

SNC Partner Name

All

sap_snc_qop

SNC Quality Of Protection

All

sap_snc_sso

SNC Single Sign-On

All

Database (DB) Connection Type Field

Fields defined in a Universal Template as type DB Connection will be passed to the extension instance as a value of type dict. The dict representing the DB Connection will contain a collection of key value pairs that represent a set of fields from a DB Connection defined in the Controller. The dict will contain the following keys:

  • name
  • description
  • type
  • url
  • driver
  • max_rows
  • credentials
    • user

    • password

    • keyLocation

    • passphrase

    • token

For example:

{
  "db_connection": {
    "name": "DB name",
    "description": "",
"type": "",
"url": "",
"driver": "",
"max_rows": 5,
"credentials": {
"user": "value",
"password": "value"
"keyLocation": "value" "passphrase": "value", "token": "value",
} } }

Code Example

The DB Connection values in the fields dict can be referenced as follows:

name = fields["db_connection"]["name"]
password = fields["db_connection"]["credentials"]["password"]
max_rows = fields["db_connection"]["max_rows"]

Key to Field Mapping

The key value pairs in the DB Connection dict represent the similarly named fields that make up a DB Connection definition in the Controller. Below is a mapping of dict key name to DB Connection field name in the Controller.

dict Key

Field Name

nameName
descriptionDescription
typeDatabase Type
urlConnection URL
driverDriver
max_rowsMaximum Rows
credentialsCredentials

Note, the value of credentials is a dict that contains

dict Key

Field Name

user

Runtime User

password

Runtime Password

keyLocation

Key Location

passphrase

Passphrase

token

Token