Mapping Web Service Function Parameters to SBM Fields

The following sections provide guidance for mapping Web service inputs and outputs to SBM fields.

Input Data Mapping

The following table lists the allowable mapping between Web service inputs and SBM fields. When the Web service function is called, values in the mapped SBM fields are passed to the service.

The following considerations apply to mapping SBM fields to Web service inputs:

When you map to Text fields set as Journal fields, all data from the field is passed to the Web service.
Summation fields cannot be mapped to Web service inputs.

Unless otherwise noted, SBM field types are referenced in this table as follows:

Single selection-type fields – Refers to Single Selection, User, and Folder fields, as well as the system State field and system Project field.
Multiple selection-type fields – Refers to Multi-Selection, Multi-Group, Multi-Relational, and Multi-User fields.

Web Service Input Data Type	Allowable SBM Field Mapping	Notes
Boolean	Binary/Trinary	For Binary/Trinary fields set as check boxes, "true" or "false" are mapped. Listbox and radio button labels are mapped.
Date/Time	Date/Time	Date/Time field values are converted to XML date/time format. Coordinated universal time (UTC) is assumed.
Enumeration	Single selection-type fields	For details, refer to Enumeration Mapping Settings.
List Types	Multiple selection-type fields	For multiple selection-type fields, selected values are passed to the Web service as a comma-separated string.
Number (including floating point)	Binary/Trinary Date/Time Numeric Single selection-type fields Single Relational Sub-Relational	For Binary/Trinary fields, 1 or 0 are passed to the Web service. For Date/Time fields, integers are interpreted as Unix time, which is the number of seconds since Jan. 1, 1970 in UTC. For Numeric fields, truncation could occur if the SBM field is set as a floating point and is mapped to a Web service integer input. For Single Relational fields, the TS_ID from the relational field table is passed to the input as the data value. For single selection-type fields, the TS_ID from the TS_SELECTIONS table is passed to the input as the data value. For Sub-Relational fields, SBM passes the database value of the field in the related item. If this value is text, SBM passes 0 to the Web service.
Text	Binary/Trinary Date/Time Single Relational Single selection-type fields Multiple selection-type fields Numeric Text Sub-Relational	For Binary/Trinary fields set as check boxes, "true" or "false" are mapped. Listbox and radio button labels are mapped. For Date/Time fields, strings must be in XML date/time format and are assumed to be in coordinated universal time (UTC). For single selection-type fields and Single Relational fields, the field display value is passed to the Web service as a string. For multiple selection-type fields, selected values are passed to the Web service as a comma-separated string. For Numeric and Text fields, the values are passed as text. For Sub-Relational fields, SBM passes the display value to the Web service.

Output Data Mapping

You can map Web service outputs to application fields based on the following information. When the function is called, data in fields mapped to the inputs is passed to the service; the Web service passes data back based on output field mappings.

Consider the following information when mapping Web service outputs to application fields:

You can only map one application field to each Web service output.
Depending on your workflow configuration, the Web service may overwrite default values for fields mapped to Web service outputs. Field dependencies may also be ignored. For example, if a Web service runs for a post-transition context, default field values that are specified for the transition are overwritten by values sent from the Web service.
When mapping Web service outputs to selection-type fields, invalid values passed by the Web service are dropped. For example, if the Web service passes a value of "Defect" to the mapped Item Type field, that value is dropped if "Defect" is not a valid selection for that field. For best results, map fields that allow single selections, such as User and Single Selection fields, to Web service enumerations to ensure that values are properly mapped. For details, refer to Enumeration Mapping Settings.
When you map to Text fields set as Journal fields, data from the Web service replaces existing text, even if you have the Append Only check box selected for the field.
Summation and Sub-Relational fields cannot be mapped to Web service outputs.

Unless otherwise noted, SBM field types are referenced in the following table as:

Single selection-type fields – Refers to Single Selection, User, and Folder fields, as well as the system State field and system Project field.
Multiple selection-type fields – Multi-Selection, Multi-Group, Multi-Relational, and Multi-User fields.

Web Service Output Data Type	Allowable SBM Field Mapping	Notes
Boolean	Binary/Trinary Numeric Text	For Binary/Trinary fields, True maps to 0; false maps to 1. Trinary field values are never returned by the Web service. For Numeric fields, 0 maps to 1; non-zero maps to 0. For Text fields, "True" or "False" values are returned by the Web service.
Date/time	Date/Time Text	For Date/Time fields, returned strings are assumed to be in coordinated universal time (UTC). For Text fields, the returned string is added in XML date/time format.
Enumerations	Single selection-type fields Text	For single selection-type fields, enumeration types are matched to selection field values by name. If the Web service sends a value that is not valid for a mapped field, the value is dropped. For best results, map all enumerations to selection field values. For Text fields, the Web service enumeration type is added to the field as text.
List Types	Multiple selection-type fields Text	For multiple selection-type fields, each item in the list that matches a selection value is passed by the Web service. Items that do not match SBM selection values are dropped. Matching is by selection name. For Text fields, each item in the list is separated by a comma, and the entire list is added to the Text field.
Number (including floating point)	Binary/Trinary Date/Time Numeric Text Single Relational Single selection-type fields	For Binary/Trinary fields, "true" is mapped to the first value; "false" is mapped to the second value. The first and second values are specified on the Options page for the Binary/Trinary field. For Date/Time fields, integers are interpreted as Unix time, which is the number of seconds since Jan. 1, 1970 in UTC. For Numeric fields, truncation could occur if the SBM field is set as a floating point and is mapped to a Web service integer output. For Text fields, the Web service numeric value is added to the field as text. For single selection-type fields and Single Relational fields, numbers are interpreted as the selection's TS_ID.
Text	Multiple selection-type fields Numeric Single selection-type fields Single Relational Text	For multiple selection-type fields, values must be passed as a comma-separated string. For single selection-type fields and Single Relational fields, data passed from the Web service must match the display value of the SBM selection. For Numeric fields, non-numeric values are passed as zero. For Text fields, exact text passed by the Web service is added to the SBM field.