Data sources

A data source defines where the data that will be processed in the survey, is loaded from. A data source can either load data objects from Omada Identity or SQL objects from a SQL data source.

Fields in the data source are mapped to relevant fields on the survey object.

Typically, you will want to apply filters to the returned data objects. This is done differently depending on what data source you use, and whether you want to use scope variables in the filters:

• SQL data source - with a SQL data source, the survey object is loaded with data resulting from executing a SQL query. This can be relevant if, for example, you want to run a survey loaded with resource assignments from the Warehouse (ODW).

  • There are some considerations you want to acknowledge when writing the SQL query for a survey. Refer to the Data Sources chapter for details.
  • Filters for SQL data sources are written in the query. It is possible to use scope variables in the query.
  • A SQL survey supports multiple rows per object in order to allow multivalued fields.

• Data object’s data source - loads data objects of one or more Omada Identity data object type in the survey.

  • Data source fields:

    • Values on the data object type are mapped to relevant fields on the survey object.
    • The value mapped to the survey object can either be the value of a property on the source object itself, the result of a reference path expression, or the value of a fixed field.
    • There are some rules on how properties can be mapped.

  • Data source filters - you can define any number of filters to the data object’s data source . The filters are used to limit which data objects are loaded into the survey. Data source filters can only be applied to an Omada Identity data object source.

    • The right-side of a data source filter can be the name of a scope variable. By using this it is possible to limit which data objects are loaded into the survey based on the selections made by the user who launches the survey on the survey initiation screen.
    • You can use a reference path expression to define a filter on a referenced property.

• Scope variables - they allow you to define variables that can be used to filter the data objects returned in the load from the data source when a survey is launched. These are the scoping options available to the user launching the survey.

  • The scoping options can be configured to allow, for example, limiting the scope on a resource assignment survey for identities that belong to a certain org. unit.
  • Scope variables can also be used in a SQL query data source.

• Child object reference property - this property allows you to define which property will be used for parent/child surveys. When not set, a standard survey will be generated.

Data sources Markup language

A survey template is authored in the SurveyTemplateML xml language. The schema definition file, SurveyTemplateML.xsd.

Attributes

The table below lists the available attributes for dataSource:

Attribute	Description
Type	Indicates if data should be loaded from Omada Identity (dataObjects) or from SQL (sqlObjects).
Name	The name attribute can be used to add a descriptive name to the data source.
DataObjectType (dataObjects only)	The system name of a data object type in Omada Identity.
ConnString(sqlObjects only)	The Name of a data connection object. Data connection objects contain a connection string to a database.
Threshold	Controls the number of objects loaded into the survey.It can be used during testing of a survey template to prevent that more than a certain number of objects are loaded.The threshold setting should only be used for testing purposes.
childObjectRefProperty	This property is optional. It is a system name of a reference property on the data object type of the data source. If provided, survey questions will be generated for the values of this reference property on the data objects retrieved from the data source.

The table below lists the available attributes for dataSourceFields:

Attribute	Description
KeyField	Denotes the key field in a SQL query.
Field	DataObject survey. Denotes the field in the data source. Field should be either: The system name of a property, the name of a fixed field only these are allowed: Id, CreatedBy, DisplayName, or a reference path.SqlObject survey: Denotes a column name in the query
mapTo	The objectType property the field is to be mapped to.
datatype	It is possible to specify the dataType of the field. This is however not a requirement.
mapFrom	This is an optional property. Only applicable if the childObjectProperty is set for a data object type data source. The attribute is used to determine if the data source field should be mapped from the parent or the child object.
fieldIsConstant	(DataObjects only) When set to true, the value in the field attribute is treated as a fixed literal value assigned directly to the mapped survey object property, rather than as the name of a property to read from the source object. The value is converted to the target property type. Comma-separated values are supported for multi-value reference or set properties. Not supported for SQL object data sources.

Configurable ownership in surveys

Ownership survey templates can be configured to write the accepted owner to a specific, custom owner property instead of using the default property determined by the object type.

To use this, add SURV_OWNERPROPERTY to the survey object definition and populate it with the system name of the target owner property (for example, OWNERREF). The survey template can do this automatically using a constant field mapping on the data source — see Constant field mapping for DataObjects data sources below.

When the proposed owner accepts ownership, the ownership post action reads SURV_OWNERPROPERTY and writes the new owner to the configured property. In transfer ownership scenarios, the previous owner is removed before the new owner is added.

Survey objects without SURV_OWNERPROPERTY continue to use the standard object-type-based ownership behavior. Mixed templates are supported, where some survey objects use the configurable write-back path and others follow the standard path.

info

For configuration details, see Survey object and Data sources.

Constant field mapping for DataObjects data sources

DataObjects-based data sources in survey templates now support constant field mappings. In the survey template XML, mark a dataSourceField with fieldIsConstant="true" to treat the field attribute value as a fixed literal value assigned to the target survey object property, rather than as the name of a property to read from the source object.

<dataSourceField field="OWNERREF" mapTo="SURV_OWNERPROPERTY" fieldIsConstant="true" />

The value is converted to the target property type. For multi-value reference or set properties, comma-separated values are supported.

note

Constant field mapping is not supported for SQL object data sources. For SQL data sources, define constant values directly in the SQL query.

dataSource filters

A dataObjects data source can have a number of data source filters. The right-side of a data source filter can be the name of a scope variable. For more information, see the Data source filters section.

The table below list the available attributes for dataSourceFilter:

Attribute	Description
Path	The reference path to a data object type.
Left	The system name of the field (property) the filter will apply to.
Operator	The match requirements for the right side Possible values: Eq – Equal to Neq – Not equal to Lt – Less than Gt – Greater than Gteq – Greater than or equal to Lteq – Less than or equal to Contains – Contains the value
Right	The right side of the filter. Can be a scope variable.

Scope variables Markup language

The scopeVariables controls the scoping options that are available to the user in the initiate activity of the survey process. The scoping options can be configured to allow, for example, limiting the scope on a resource assignment survey to resource assignments belonging to a specific system.

Attributes

The table below list the available attributes for scopeVariable:

Attribute	Description
Name	The name of the scope variable.
Title	The text that is displayed in the user interface.
Property	Specify the objectType property the scope variable relates to.
DataType	The dataType of the property. Possible values: Reference String DateTime Boolean* Integer
Requires Value	True/False. If set to True the scope variable must be set when launching the survey.
DerivedValues	A reference path that is evaluated using the scope variable's referenced data object(s) as starting point.
DeriveLevels	The number of recursions to make if using derivedValues.
ShowInUI	Whether or not the scope variable should be displayed in the survey initiation activity.

Example

  <scopeVariables>

  <scopeVariable name="@system_var" title="Include assignments for resources belonging to this system" property="SYSTEMREF" dataType="reference" requiresValue="true" />

  <scopeVariable name="@changedlaterthan_var" title="Only resource assignments that have been changed since this date" property="DEADLINE" dataType="dateTime" />

</scopeVariables>

Scope variables in Filters

Scope variables can be used in data source filters (if the data source type is dataObjects) and in a SQL query (if the data source type is sqlObjects).

DerivedValues

On a scope variable it is possible to state a derived values expression. The purpose is to be able to make a survey of (for example) all identities belonging to a certain org. unit as well as all identities belonging to all descendant org. units.

Example

<scopeVariables>

    <scopeVariable name="@orgunit_var" title="Include assignments for identities belonging to this org. unit (and all below)" property="OUREF" dataType="reference" requiresValue="true" derivedValues="\PARTENOU" deriveLevels="3"/>

  </scopeVariables>

In the attribute derivedValues it is possible to specify a reference path that is evaluated using the scope variable's referenced data object(s) as starting point. In the attribute deriveLevels it is possible to state the number of recursions to make. In the example we only want to go 3 levels down the org. tree.

info

The example above is based on org. units, but the feature supports all reference properties.