Property Element

For each database object, there are a number of properties; and these elements map the incoming details to the correct destination properties.

Each Property element maps a column of source data to a single property (or column) of an object in the central compliance database for FlexNet Manager Suite. Each Property also contains business rules to manage the processing needed to convert from the data source to the destination database.

Example

<Property 
        Name="Serial Number" 
        Type="serialnumber" 
        Update="Always" 
        Value="SerialNo" 
        ValueType="Field Value" 
        UseForMatching="True">
</Property>

Contains

No child elements: Property is an empty XML element, using only its attributes.

Contained by

Object.

Supported attributes

DataType

Optional, but required when IsCustomField=true. It declares the data type of the custom property so that the data is correctly parsed. Valid values are:

• int
• date
• numeric
• boolean
• string (default).

Tip: For standard (non-custom) properties, the data type, format, and precision for each destination property is automatically read from the compliance database schema.

FieldMask

Identifies any constant prefix and/or suffix on values in the incoming property records that do not exist in the target database. When the Business Importer assesses incoming records for matches in the target database, it first augments the target key value with the additional data in the field mask, and then assesses the match.

The formats for declaring this value are:

FieldMask="'prefix'+ [targetColumnName] + 'suffix'"
FieldMask="'prefix'+ [targetColumnName]"
FieldMask="[targetColumnName] + 'suffix'"

Notes:

• In general, the value replacing targetColumnName will be the same as the value of the Type attribute — the name of the target column in the target database.
• This column name must be enclosed in literal square brackets, indicating "value of".
• The prefix and suffix placeholders can be replaced with any text string.
• The plus sign (+) is required for string concatenation. White space around this operator is optional.

For example, suppose your source data includes location names with a constant prefix Locn-, so that the source data represents Australia as Locn-Australia. However, in the target central operations databases, the locations do not have this superfluous prefix, and there the location is simply called Australia. Without some intervention, the source data could never update records in the target database, because the values are not matched. To solve this, declare:

FieldMask="'Locn-'+[groupcn]"

This mask concatenates the fixed prefix with each value of the groupcn column in the target database, and the combination is tested against the incoming data. Therefore, the incoming record Locn-Australia is matched by the evaluated FieldMask of Locn-Australia, and the Business Importer now knows to update the entry for the Australia location in the target database.

Format

Declares the format of date/time values (when DataType="date") and numeric values (when DataType="numeric"). These are formats identified for the source data, allowing the Business Importer to convert to the format required for storing in the target database. The following references may assist:

• For standard date/time formats: https://msdn.microsoft.com/en-us/library/az4se3k1.aspx
• For custom date/time formats: https://msdn.microsoft.com/en-us/library/8kb3ddd4.aspx
• Decimal number formats: https://msdn.microsoft.com/en-us/library/d8ztz0sa%28v=vs.110%29.aspx
• Integer formats: https://msdn.microsoft.com/en-us/library/8wch342y%28v=vs.110%29.aspx

IsCustomField

Optional. Boolean:

• true means that this property is a custom property added to the compliance database
• false (the default) means that the property is a standard one documented in the FlexNet Manager Suite Schema Reference PDF file.

See also the DataType attribute. For more details on these attributes, see Custom Properties.

Note: The automatic creation of custom properties defined in the adapter XML file is supported only for on-premises implementations when the adapter is running on the central application server (and not supported on inventory beacons where the adapter runs in disconnected mode). However, once a custom property exists in the operations databases, any adapter can add values to the custom property.

Custom properties are only available for the following objects in the compliance database:

• Application
• Asset
• Computer
• Contract
• Purchases (Purchase Order header and lines)
• Software License
• User.

For more about customization, see the FlexNet Manager Suite System Reference PDF.

MatchingMask

Supported only for on-premises implementations where the adapter is running on the central application server (and specifically not permitted for adapters running on inventory beacons). Except when dealing with properties of enterprise groups, this is required when MatchingMode="like", for which it declares the pattern used to find matching records. The value of the property in the incoming data stream is represented as the special placeholder [value] (with the square brackets).

The MatchingMask attribute uses standard SQL syntax to declare a pattern to match. The exact syntax varies, depending on the value of the ValueType property. For example, to match a record that ‘contains’ the incoming value (with other possible content), the two syntax examples are:

• For ValueType="Fixed Value":

  MatchingMask="%[value]%"

• For ValueType="SQL Value" or ValueType="Field Value":

  MatchingMask="'%' + [value] + '%'"

Example: The following XML looks up assets (in the compliance database) by serial number based on a partial match:

<ObjectName="asset" Type="asset" Output="assetoutid">
   <Property 
       Type="SerialNo" 
       Name="SerialNo" 
       Value="SerialNumber" 
       ValueType="FieldValue" 
       UseForMatching="True" 
       MatchingMask="%[value]%" 
       MatchingMode ="like"/>
   … 
</Object>

MatchingMode

Optional. Specifies how this property will be matched against the existing data in the central compliance database. Available values:

• = (the equals sign) (default). Matches must be exact. (MatchingMask is ignored.)
• like allows the use of a matching mask, declared in the MatchingMask attribute.
  Tip: The MatchingMask attribute is not required in the special case of properties of enterprise groups.

Name

Mandatory. This is the friendly name of the property. The attribute is exclusively used in the adapter XML file, and need not match either incoming or target columns names (for which see Value and Type respectively).

OnMissingFieldValue

Optional. This attribute dictates the behavior of the Business Importer when this clash occurs:

• The adapter XML file defines an incoming column name (declared in Value when ValueType="FieldValue")
• The source data does not include a column of the same name.

Support values are:

• Empty string, not declared, or given any value other than the following two: TheBusiness Importer raises an error to highlight that you have mapped a source column that does not exist to a target column.
• Discard Property means that records for the incoming instances of the object are created and updated, but the missing property is silently ignored.
• Discard Object means that no instances of the object are created in the target database.

For example, suppose you have the following Property on a location Object in your adapter XML file:

<Property 
    Name="Name" 
    Type="groupcn" 
    OnMissingFieldValue="Discard Object" 
    Update="Never" 
    Value="Loaction" 
    ValueType="FieldValue" 
    UseForMatching="True" 
    RegExSplit="/" />

The combination of ValueType="FieldValue" and Value="Loaction" tell the Business Importer to map input from the Loaction column into the target database. However, if the source data does not share the same typographical error, and instead has a column called Location, the proposed column name cannot be found. Now OnMissingFieldValue="Discard Object" means that no locations will be imported, because the entire object is discarded based on the failure to find the key field. The fix, of course, is to correct the error in the adpater XML file.

RegexOption

Optional. Specifies the regex options applying to the RegexString attribute. Supported values are:

• Cultureinvariant specifies that cultural differences in matching methods are ignored.
• Ecmascript specifies that ECMAScript compliant behavior is enabled for the expression. (ECMAScript is Javascript compliant with the ECMA-262 standard.)
• Ignorecase specifies case-insensitive matching.
• Ignorepatternwhitespace specifies that unescaped white space is excluded from the pattern.
• Multiline specifies multi-line mode.
• Rightoleft specifies that the search moves from right to left instead of left to right.
• Singleline specifies single line mode.
• None (default) means that no options are used.

RegexOrder

Optional. May only be used with the GroupCN property of enterprise groups; and is used in conjunction with the RegexSplit attribute. This RegexOrder attribute declares whether the compound string of enterprise groups reads from parent down to child (leaf node last), or from child up to parent (leaf node first). It supports the following values:

• Regular (default) means the parent-to-child values are read from left to right. A GroupCN value ordered this way might be:

  USA/Boston/100 North Washington

• Reverse means the values are read leaf node first, with parents to the right. A GroupCN value ordered this way might be:

  100 North Washington/Boston/USA

RegexReplace

Optional. Specifies one or more characters or strings in the incoming values for the current Property that are to be replaced by the corresponding value(s) declared in the RegexReplaceBy attribute. (The RegexReplace and RegexReplaceBy attributes must be considered as a pair.)

• To specify multiple strings to replace, separate them with either a comma (,) or hash (#) character.
• The number of separate strings in this RegexReplace attribute must match the number in the RegexReplaceBy attribute (any extra values in either one are ignored).
• Spaces are significant, and are included in the pattern matching. (Don't leave extra spaces around the separator characters.)
• With multiple strings, order is correlated between these two attributes (the first target string becomes the first replacement, and so on).

Example:

RegexReplace = "Microsoft Corp.,Microsoft Corporation,Adobe Inc."

RegexReplaceBy

Optional, but required when RegexReplace is used. Specifies one or more characters or strings used to replace the corresponding value(s) declared in the RegexReplace attribute. (The RegexReplace and RegexReplaceBy attributes must be considered as a pair.)

• To specify multiple replacement strings, separate them with either a comma (,) or hash (#) character.
• The number of separate strings in this RegexReplaceBy attribute must match the number in the RegexReplace attribute (any extra values in either one are ignored).
• Spaces are significant, and are included in the replacement text. (Don't leave extra spaces around the separator characters.)
• With multiple strings, order is correlated between these two attributes (the first replacement substitutes for the first target string, and so on).

Example:

RegexReplaceBy = "Microsoft,Microsoft,Adobe"

When you combine the examples given for both attributes in the processing of this Property (such as the name of a vendor), all instances of either “Microsoft Corp.” or “Microsoft Corporation” are standardized to “Microsoft”, and all instances of “Adobe Inc.” are standardized to “Adobe”.

RegexSplit

Optional. Specifies the character on which to split the incoming property into separate values. May only be used with the GroupCN property of enterprise groups. The GroupCN values may contain an entire path through the tree of enterprise groups in a single column (imported as one Property). For example, a location may be specified as the following path:

USA/Boston/100 North Washington

The goal is to spit this path into separate location entities, organized in parent/child relationships to form a tree. The RegexSplit attribute specifies the character separator (in this example, the forward slash) used to split the GroupCN values into multiple database entities.

The above example value can be entered as separate locations in the compliance database, with the correct parent-child linkages, using the following XML:

<Object Name="Location" Type="Location" 
        Output="locationoutid" Create="True" >
    <Property
        Type="GroupCN"
        Name="Name"
        Update="Never"
        Value="LocationFullPath"
        ValueType="FieldValue"
        UseForMatching="True"
        Regexsplit="/" />
    <Property
        Type="GroupExID"
        Name="Parent ID"
        Update="Never"
        Value="locationoutid"
        ValueType="FieldValue"
        UseForMatching="True"
        UseNullValueForMatching="removeproperty"/>
</Object>

RegexString

Optional. Sets the regular expression applied to incoming values of this property. Matched data is extracted and included in the import, while those parts of values that were unmatched are discarded. If there is no match found in an incoming value of this property, the output is am empty string. Processing of the regular expression may be modified by the value of RegexOption.

Type

Mandatory. The type uniquely identifies the property within the object in the compliance database, and must be an exact match for the name of an existing database column. Details of the compliance database schema are available in the FlexNet Manager Suite Schema Reference PDF file. Custom properties are supported on relevant objects (see IsCustomField).

Important: Do not set the Type attribute equal to the database ID of the enclosing object. (For example, if this is a property of an Asset object, do not set the Type attribute to AssetID.) Database IDs cannot be directly referenced, set, or updated by the Business Importer. Pointing this attribute to a database ID will produce erratic results and likely crashes of the Business Importer.

Update

Optional. Sets the business rule for updating the property if there is already a value in the central compliance database. Possible settings:

• Always (default) means that any new incoming value always overwrites the existing value. This includes incoming blanks or nulls removing pre-existing values in the compliance database. (To prevent the latter, use Do Not Blank instead.)

  [Any new value]  >>  [Any existing value]  =  [New value]

• Never means any existing value in the compliance database is preserved, and any new incoming value is ignored. This might be used, for example, when you only want to look up a property, without updating it.

  [Any new value]  >>  [Any existing value]  =  [Existing value]

• If Blank means that value is updated only when the operations databases has this column blank (null value). However, if the database already contains a value here, it is preserved, and the incoming value ignored.

  [Any new value]  >>  [Any existing value]  =  [Existing value]
  [Any new value]  >>  [Blank value]         =  [New value]

• Do Not Blank means the property in the target database will be updated except when the incoming value is empty. An incoming null leaves any existing value in the compliance database intact.

  [Any new value]  >>  [Any existing value]  =  [New value]
  [Blank value]    >>  [Any existing value]  =  [Existing value]

Note: Most properties in the supplied adapter XML files (for both disconnected mode on inventory beacons, and for connected mode on the central application server of an on-premises implementation) are set to Do Not Blank to prevent accidental removal of existing data when the adapter is used. The exceptions to this general principle are:

• The Property element has UseForMatching="true", or
• The parent Object element has Create="false" and Update="false".

UseForMatching

Optional. Boolean:

• False (default) means this property plays no part in matching incoming data with existing records in the compliance database.
• True means this property (perhaps in conjunction with others) acts as a key for retrieving existing records.

Note: For most import objects, you cannot save an existing adapter or create a new adapter without setting UseForMatching="True", or if defining import rules for attributes/properties using the UI without selecting the Use this property for matching existing data check box. If using the UI and do not select the check box but the chosen adapter requires it to be checked, then a warning message is displayed and you will not be able to save the new adapter until the issue is corrected. The only import objects that do not require UseForMatching (or corresponding UI Use this property for matching existing data check box) are:

• Contract Responsibility
• Contract Asset
• Contract License
• Operator Role
• Payment Schedule License
• Payment Schedule Asset
• Purchase Order Line Asset
• Purchase Order Line License

UseNullValue ForMatching

Optional. Sets the business rule to apply when the value is empty or null and UseForMatching=true. Note that this is not a Boolean. Possible values are:

• True means the null value will be used for matching, and corresponding records with a null or empty value for this property will be returned.
• False (default) means the incoming record containing the empty or null value is rejected.
• Ignore means the lookup is performed without this property. This requires the use of multiple properties for matching, and the values of the other matching keys are used.
• RemoveProperty is a synonym for Ignore.

Value

Mandatory. Defines the value of the property to be written into the compliance database. Depending on the value of the ValueType attribute, the Value may be:

• A literal value
• The name of the column in the source data that includes the appropriate value
• The Output attribute from a preceding Object in the current Import
• A fragment of SQL (optionally including columns from the data source) that defines the value.

Note: If ValueType="Field Value" and the Value attribute is empty, the property is ignored during the import.

ValueType

Optional. Determines how the Value attribute for the Property should be interpreted:

• Field Value (default): in this case the Value attribute contains either of:
  • The name of a column from the initial query (either a column name in a CSV or XLSX source file, or if the data is a result of an SQL query, the SQL column name)
  • The value of the Output attribute of one of the preceding Object elements in the current Import. For example, suppose that an update to a location Object had an Output attribute set to locationoutid, which saves the ID of the affected record. This can now be written as a Value for a Property on a different Object, creating a foreign key to that location record.
• Fixed Value: the Value attribute contains the value itself. This may be a value-by-reference, where the Value attribute specifies a reserved name in square brackets, such as [TODAY] (which inserts the current date/time), or [ROWNUMBER] (which inserts the number of the current row in the incoming data stream).
• SQL Value: the Value attribute contains an SQL expression that, when run on the source database, returns the value. This fragment may include a column from the data source.