Creating converters for your connectors

Converters are essentially python functions that are specifically intended for transforming connector data before sending it to Oomnitza. I don't have any more detailed documentation, but I'll give you an overview here.

The basic format of a converter is as follows:

[converters]
name_of_converter:
     <python code>
     return <value to return>     

and is called to transform an value using:

mapping.<oomnitza_field_id> = {"source": "value_from_payload", "converter": "name_of_converter"}

You'll notice that the name_of_converter​ looks like a function, but lacks parentheses or arguments. When ever a converter runs, it's passed two values: record and value. 

record​ contains the entire json payload we retrieve for a given asset from the source system as a dictionary, which may look something like:

{
    "serial_number": "S1234567890",
    "barcode": "A1234",
    "email": "[e-mail]",
    "memory_mb": "5128"    
}   

value​ contains the specific value that we passed in the "source": "value_from_payload" section of the mapping. For more on creating mappings, see our article on custom field mappings.

Beyond that, the rest is Python. I've included a couple of basic examples below. 

Example: remove domain from email address:

mapping.ASSIGNED_TO = {"source": "username", "converter": "email_to_user"}

[converters]
email_to_user:
    if not value:
        return value    
    return value.split("@")[0]

Example: remove leading character from SN

mapping.SERIAL_NUMBER = {"source": "username", "converter": "remove_s"}

[converters]
remove_s:
    if not value:
        return value    
    if value[0] == S:
        return value[1:]
    else:
        return value 

Please note that I start each of converters with:

    if not value:
        return value 

This isn't always necessary, but it allows null / empty values to go through the connectors regular processing, making error handling easier.

Please note that there's no requirement to return the value or use the value at all in the transformation. For example, we can return or transform a field straight from the record:

Example: concatenate SN and Barcode 

mapping.UNIQUE_ID = {"source": "username", "converter": "concat_sn_and_barcode"}

[converters]
concat_sn_and_barcode:
    if not record["serial_number"] or record["barcode"]:
        return none    
    return record["serial_number"] + record["barcode"]

The possibilities are pretty much endless. In addition to the basic functions outlined above, far more advanced functions can be created. Since it's using python, you're free to import and utilize libraries to aid in your transformations. Two that are already used by the connector that I tend to use are python requests and python arrow. 

Requests is handy for validating data sources or integrating data from an external API. It can also be used against Oomnitza's own API to check for the existence of certain information, for example, checking whether or not a user exists before pushing a value into Oomnitza's Assigned To field. 

Arrow is handy for date/time transformations to make sure values are pushed to Oomnitza in regular formats. It can also be used to return the current time, which is helpful for keeping track of connector syncs on an individual asset level:

...
current_timestamp:
  import arrow
  return arrow.now().timestamp