Mapping extended connectors

Oomnitza's Mapping Screen

Oomnitza's mapping screen is used in imports and connectors to allow Oomnitza admins to create mappings between systems and define how data is imported into Oomnitza. 

Mapping Fields

Values from the connector can be still dragged to Oomnitza fields to create mappings, but now fields can be selected from a dropdown as well, making it easier to find your desired fields. 

 

Create Fields While Mapping

You can also create new fields directly in Oomnitza's Assets or Users module straight from the Mappings Page. New fields can be created through both types of mapping, when dragging, or when using the dropdown, making it easier to bring new information into Oomnitza on the fly. 

Adding Custom Mappings

While Oomnitza tries to maintain detailed lists of available fields through the mappings screen, sometimes, due to changes to the source systems API, or the presence of custom data, it's necessary to custom mappings. These can be added using the "+" button at the top of the connector mappings:

From here, you'll need to give the field a name, and specify the path to that field as it's returned to Oomnitza via the source system's API. The system is made to be flexible and will recognize paths that are enclosed or not enclosed in double-curly brackets (e.g. {{custom_field}}) or custom_field) or nested fields that use either dot, or bracket notation (e.g. {{profile["custom_field"]}} or profile.custm_field

For example, if the data coming from the source system appears as so:

{
    "profile": {
        "field_1": "value 1",
        "field_2": "value 2"
    },
    "status": "value 3"
}

You can access data the following ways, and more:

value 1: profile.field_1

value 2: {{profile["field_2"]}}

value 3: status

For any questions or help creating custom mappings for your extended connectors, please reach out to [e-mail].

The "Adding new field" function is also very useful for hardcoding certain values within the Oomnitza side. You can achieve this by using a syntax like {{"My hardcoded value"}}. While you technically can also do this by directly typing the hardcoded value into the target field on the right side of the connector, defining it as a new field on the left and using the mapping to a field within Oomnitza will also allow you to use the filtering of such field to e.g. only update the field in Oomnitza if it is empty. This can e.g. be used for user integrations and there specifically to default a role for new users only, meaning in the filter criteria on the right side you would the select to only update this field in Oomnitza if it is empty. Another use case for this would be to perform string operations to e.g. concatenate various fields as well as hardcoded segments into a username from the source data to match the username in Oomnitza in case you are not able to retrieve a matching username from the source data.

Jinja2 Templates

Oomnitza's Extended Connectors allow the use of Jinja2 Templates in order to transform data being retrieved by the connector. 

• To use the string functions or string concatenations, you can include string operations within the double curly brackets. Examples for this are:
  • {{serial_numer + "-" + asset_tag}}
  • {{serial_numer.lower()}} # using the python lower() method for str type variables
  • {{full_name.split() | first | capitalize}} # combine the Python syntax and Jinja filters to return the first letter of the full name in upper case
  • {% if full_name.lower().startswith('m') %}STARTS WITH M!{% else %}NO IT DOESNT{% endif %} will return the string "STARTS WITH M!" in case the full name start with the letter m and will return the string "NO IT DOESNT" otherwise
  • concatenations of functions is possible as long as you stay within a single line
  • all common string methods available within Python are supported, see a complete list here: https://docs.python.org/3.6/library/stdtypes.html?highlight=str#string-methods  
• String fields that are dropdowns will allow you to select the new value from a drop down.
• Checkbox fields will allow you to update the value to Yes or No.
• Date fields will allow a variety of functions, including hard-coding a date or dynamically calculating a date based on other dates and date functions.
• Sometimes you'll want to ensure that data being retrieved is accepted as-is from the external system, such as cases with dates and phone numbers that use the '-' symbol to separate numbers. In these cases, values may be interpreted as math equations instead of strings. To prevent this, "| as_is" can be added to the template to interpret the field as a raw input. For example: {{phone_number | as_is}}.

Mapping Last Sync Time

It's often useful to pull in a given object's last sync time. This allows for monitoring of syncs and helps ensure that devices are being continually updated. To add a Last Sync time to a connector, you would proceed as follows:

• Within the connector go to the mappings page and add a new field (on left side above fields using + sign)

• Give the field a name like "Last Sync Time"

• Add following Jinja statement:

  {% set datetime = import('datetime') %}{% set rightnow = datetime.datetime.utcnow() %}{{rightnow}}

• Map this to a date/time field in Oomnitza

We recommend setting this field to not add updates to the history since it will get a new value every time the connector runs and will as thus make the history of the asset very busy

Filtering Results

The Oomnitza Connector allows for results to be filtered, ensuring only the desired objects are updated. To add filters to a connector, click the cog icon in the upper left of the connector mappings page. 

From this panel, you're given the following options:

Restore archived records: Determines whether or not the connector restores archived assets when an asset is matched.

Always create/update the record in OOMNITZA: Ensures that records are always created/updated.

Create/update the record in OOMNITZA if: Allows filters to be applied to the connector, ensuring only certain objects are created or updated. 

Restrict Access for Users While Mapping

You can Restrict Access for users to Oomnitza from the Mappings Page by selecting the radio button for True. This means that any user who is loaded into Oomnitza via this connector will not be able to log in to Oomnitza using Single Sign On. The Restrict User flag on their user details page will be marked as yes which can be changed by the admin.