Customization Functions
Here's the list of customization functions available for use with your mappings:
utils.truncate(input_value, length)
input_value: String (mandatory)
length: Integer (mandatory)
This method truncates the input string beyond the given length parameter and returns the remainder of the string.
utils.text_to_int(input_value, default_value)
input_value: String (mandatory)
default_value: Integer (optional)
This method converts the input_value to an integer and returns it, provided it's a valid integer in string format. Otherwise, if a default value is provided then that will be returned. Else an exception is raised.
utils.text_to_float(input_value, default_value)
input_value: String (mandatory)
default_value: Float (optional)
This method converts the input_value to an float and returns it, provided it's a valid float in string format. Otherwise if a default value is provided then that will be returned. Else an exception is raised.
utils.multi_to_single(input_value, priority_list)
input_value: An array of selected values for the multi-select field. (Mandatory)
priority_list: An array of display values in order pf priority to be considered when mapping it to the single select field on the other side. The array is allowed to be empty. (Mandatory)
This method picks one choice from the possibly many values in the input_value, based on the priority_list provided. If no value in the priority_list matches any of the values in the input_value then the first value is returned. If the priority_list is empty then too the first value is returned.
utils.text_to_single(input_value, default_value, fetch_latest)
input_value: String (Mandatory)
input_value: String (Optional)
fetch_latest: Boolean (Optional, defaults to False)
The input_value must match the display value of the mapped single select field. In that case, the method returns that single select field's value. Else, if a default_value is provided then the same is attempted with that value. Otherwise, an exception is raised. The fetch_latest flag—when set to True—fetches the latest values from the ALM tool. This is useful to always fetch the latest values from the ALM tool (such as Jira) as you may have new values added to a drop-down type Jira field for example in the aftermath of mapping creation in Agility Connect. The default_value and fetch_latest are keyword parameters and so either or both can be given in any order as long as the argument name is used. For example, we can skip the default_value and pass the input_value and fetch_latest. For example, utils.text_to_single('value1', fetch_latest=True).
utils.concat_fields_values(input_value, field_names, separator, default_value)
input_value: String (Mandatory)
field_names: List of strings (Mandatory)
separator: String (Optional, defaults to a comma and space)
default_value: String (Optional)
This method concatenates the input_value with the values of each of the fields provided in the list of field_names. Unless you pass a separator—the separator used for the concatenation—by default—is a comma and space. If a default value is provided and if any of the fields in the field_names doesn't have a value this default value will be used. The separator and default_value are keyword arguments and so ordering is not needed if the argument name is used in the method call such as utils.concat_fields_values('value 1', ['field2', 'field3'], default_value='defval'). An error occurs if any of the field names provided in the field_names list is invalid.
utils.extract_substring(input_value, separator, ind)
input_value: String (Mandatory)
separator: String (Mandatory)
ind: Integer (Optional, defaults to 0)
This method splits the input_value string based on the separator provided and returns the value at the index denoted by ind. The ind value can be negative too. A negative value is equivalent to indexing from the end of the string, so a value of -1 means the last part after the splitting of the string. For example if the string is 'val1_val2_val3_val4' and the separator provided is '_' then the ind value of 0, 1, 2 and 3 return 'val1', 'val2', 'val3' and 'val4' respectively. An ind value of -1 returns 'val4' and -2 returns 'val3'.
utils.get_display_value(input_value)
input_value: String (Mandatory)
This method returns the display value of the provided input_value. The drop-down fields have predetermined values and are usually internally represented by ids in certain ALM systems like Digital.ai Agility. This method comes in handy in case you want the display value fetched for some reason.
utils.get_planning_level(input_value)
input_value: String (Mandatory)
This method is similar to the utils.get_display_value but it's specific to child planning levels in Digital.ai Agility. It returns the entire planning level path from the parent to the child separated by '/'.
utils.planning_level_to_label(input_value, separator)
input_value: String (Mandatory)
separator: String (Optional, defaults to '/')
Use this method to map Digital.ai Agility's planning levels to the tags/labels field on the other side. Providing the entire planning level path as input splits it based on the separator and writes each value as a tag/label to the other side.
utils.get_field_value(field_name)
field_name: String (Mandatory)
This method fetches the value of the field referred to by the input field_name. An error occurs for invalid field names.
utils.get_sprint_name(sprint_object)
sprint_object: String (Mandatory, value as returned by Jira for Sprint)
Use this method to get the name of the Jira sprint. The Jira sprint value that comes from Jira is a string that has more than just the sprint's name. This method extracts just the sprint name and returns the same.
utils.get_planning_level_project(input_value, default_value)
input_value: String (Mandatory)
default_value: String (Optional)
Use this method to get the project id of a planning level in Digital.ai Agility. The input_value refers to the planning level's name. The optional default_value refers to the default project/planning level name in case the provided planning level couldn't be located.