Models

Models are a central concept when creating a REST connector. They are use both for posting object data to an API and also when receiving object data from an API.

Models are managed from the "Model" node in the connector tree.

Below the grid you can create new models. You can create an empty model by pressing the "NEW" button, or you can create a new model based on JSON (sample or Schema Draft 4) or XML sample.

Let's start with creating an empty model.

• Name A unique name for the model.

• Description Currently purely a documentation feature for you as a REST connector designer. Provide a description of the model if it makes sense.

• Base model Used to set a base model that the new model should be based on. All members of base model is added to the new model. Base models are described in detail in its own section below.

• Namespace Used when model is sent or received as xml. If no Namespace is provided and the model is sent as xml, no namespace is assumed.

• Xml name Name of xml element when model is sent or received as xml. If no Xml name is provided, Name is assumed to be the xml elements name.

After the model has been created it is empty and pretty much useless. Press "NEW" on "Items" to create members of model

This will bring up a dialog where you can specify details about the member of the model.

• Name The name of this member of the model, must be unique in the scope of the model.

• Display name A more human readable version name of the member. If model is used as input to an operation this is what the workflow designer will see as name of member. The actual name of the member is still Name though, and if you want to create a record to use as input (as opposed to a 'Custom record') you must specify Name in that record.

• Description Currently purely a documentation feature for you as a REST connector designer.

• Type Here you select what type of member this is.

  • Boolean - true or false.

  • Integer - Type format is available. As Type format you can set int64 for big integers (default is int32)

  • Number - Type format is available. As Type format you can set float or double (larger, and default if not set)

  • Object - Used when the member is of a Model.

  • Object (embedded) - Used when the member is a Model, but the Model is only used once, so creating an independent Model is inefficient. More information about embedded models can be found below.

  • String - Type format is available. As Type format you can set date-time to indicate that the member is actually datetime. You can also set it to password to mask the value in the machine step configuration.

  • Enum - used to set that this member is of an enum. See Enum for more information.

  • Custom - Custom specification is available. With the Custom specification you can set the type for special use cases. See Custom model member for more information.

• Is array (of Model or Type) Available for all Type except Enum. Set this if the member is a collection of Type

• Constraints Constraints section depends on Type and it's members are at the moment more of a documentation nature than actual impact on usage of connector. This may change in a future version.

• Advanced This section is used to specify if member has another name in JSON or xml than it's Name. If JSON you can also specify how to handle missing value of this member ('JSON property value requirement'). Please note that this only applies to incoming models from remote API, not models you are sending to remote API. Default is to ignore missing members. You can also specify what to send if a member of a model is not set ('JSON property null value handling'). Default is to ignore the member, but you can change so that a 'null' value is sent. In the case of xml you can also specify whether the member is an attribute or a element of parent xml element and also the xml order, if that is important.

You can manually create as many members of the model as needed. You can of course also delete and edit members when needed. You can rearrange the order of the members if you like. Keep in mind that order can be important when dealing with xml.

While creating the model manually is easy, it is even easier if you already got a JSON or xml representation of it. Here is an example of a model from JSON (sample):

Types are assumed based of the example data, for instance "Prop3" is assumed to be of type Boolean since the example value of it is 'true'. This feature works for most cases, but there are cases where you need to manually specify exactly the type you need (setting an Integer to have Type Format int64 is one example). You can set all data types to 'large ones' by checking 'Use large data types'. Note that all members of type Integer will then have int64 format.

You can also create models from JSON Schema (draft 4), this is much more accurate than from sample but is not as commonly used as JSON samples. Here is an example of a model from JSON Schema:

As you might notice, id is specified as int64 already in the schema, and this will be stored in the Model. JSON Schema (draft 4) is superior to JSON Sample in almost every way but, as stated above, unfortunately not as commonly used to document REST APIs as JSON samples.

Another way to get an external representation of a Model into the REST Project is by xml. Currently only sample xml is supported, not from any schema (such as xsd). Here is an example of a model from xml sample:

Embedded models

When creating models from JSON or XML sample, inner structures of the model are created as 'embedded models'. This is new in version 6.8 of Flow, in earlier versions independent models were created. If a model is used only once it makes little sense to have an independent model. Chances are that you will end up with lots of models and the project will be hard to manage. When using an embedded model all the members of the model is located directly under the model member. This is perhaps best illustrated with an example:

Consider this structure:

{ 
        "property1":"string", 
        "property2":"string", 
        "property3": 
        { 
              "innerProperty1" : "string",                           
              "innerProperty2" : "string", 
              "innerProperty3" : "string" 
        }, 
        "property4": 
        { 
              "innerProperty1" : "string", 
              "innerProperty2" : "string",
        }
}

With independent models you would end up with models like this:

This is not wrong, it will work just fine, but as project grows larger the number of models will be problematic. With the use of embedded models you would end up with model like this:

The two extra models that was referenced by 'model1' are now embedded in the model. This of course means that the model 'property3' cannot be used by another model, but in the situations where that will not happen, this is a better solution.

Referring to an embedded model in model transformation

If you want to create an instance of an embedded model in a model transformation you refer to it as 'Model_NAMEOFMODEL.Embedded.NAMEOFPROPERTY'. An example with the 'model1' above:

public static Model_model1 modeltransform(Model_model1 input) 
{ 
var output = new Model_model1(); 
//Transformation code start 
output.property3 = new Model_model1.Embedded.property3(); 
output.property3.innerProperty1 = "a value"; 
//Transformation code end 
return output; 
}

Converting between embedded and independent models

By default all inner structures are interpreted as embedded models (possibly with the exception of JSON schemas). You can convert between embedded models and independent models in the tool after they've been created by right-clicking on their usage in the tree view and select Convert to independent model(or Convert to embedded modelif already independent). If you convert to an embedded model, the related independent model will not be removed. If the rest project tool detects that the model is not used anywhere you will be prompted with the option to delete it though.

Base models

In version 6.8 of Flow the support for base models were added. Basically a model can use another model as a base, meaning that all members of the base model are available also in the new model. Here is an example where Model2 has Model1 as base model and Model3has Model2as base model. All members of both Model1and Model2are available in Model3.