File Descriptor

File Descriptor Structure

A file descriptor can specify the following structures:

Unstructured

The file descriptor structure Unstructured, describes a flat file whose format is not known to AWM and not interpreted by AWM.

Table

The file descriptor structure Table, describes a file consisting of lines with a defined format. The way that AWM interprets the file is determined by the property delimiter (attribute: PropDelimiter) and the properties related to the file descriptor. Each line of the file will consist of values for the related properties separated by the property delimiter in the sequence of the property relation definition. At run time the values in the file are mapped to the properties as specified in the file descriptor to property relations. You can set a static value for a property reference. In this case the static value is mapped to each line of the table structured file at the corresponding position and set from or returned in the property referenced in the Target ID attribute of the property reference when writing or reading the file.

A file descriptor modelled in this way:

Could have the following content:

Argentina,Buenos Aires,South America
Algeria,Alger,Africa
Niger,Niamev,Africa
France,Paris,Europe

JSON

The file descriptor structure JSON can be used to model a JSON payload, for example, for a REST service call. If the file descriptor is intended to parse a JSON payload it is only necessary to model the part of the JSON which is relevant for the AWM application. The JSON file structure should describe which parts of the JSON payload should be mapped to AWM properties.

At every level of the structure you can model a child of type 'Element' or 'Attribute'. An element can be a JSON object, an array or a simple array specified in the element's Type attribute. A JSON attribute can be one of the following types, String, Boolean, and Number. The JSON attribute can be specified as a static value or it can point to a property via the Target ID attribute. If the JSON attribute is pointing to a property via a Target ID the attribute value is taken from the current value of the property at run time and the property value is set by the value returned in the corresponding JSON attribute.

JSON array elements represent object arrays, which contain additional elements or attributes. Simple arrays are non-object arrays which only contain String, Numeric, or Boolean values. Similar to attributes, their values can be mapped to or taken from a modelled property or can be a static value. AWM currently only supports single-value simple attributes. Attempting to parse a JSON document with a multi-value simple array will result in an error message.

A file descriptor structure JSON has the additional action Generate Structure in the context menu of the model editor. This action enables you to generate the file descriptor's structure based on a given JSON payload. Calling this action opens the Generate Structure wizard. The wizard enables you to paste a JSON formatted payload in the editor window. Typically REST based applications offer a feature to capture the payload sent with a request. This payload capture can be cut and pasted into the wizard's editor window.

Clicking Preview displays the elements of the structure which will be added to the file descriptor's structure definition. The generation does not overwrite pre-existing elements of the file descriptor. If the JSON structure cannot be successfully parsed, an error message is displayed in the header of the wizard when clicking Preview or Finish. When you click Finish and no JSON parser errors are encountered, the file descriptor's structure is generated in the model editor. The type of an attribute (String, Number, or Boolean) is generated depending on the value type of the attribute in the given JSON payload.

This function can be used to simplify the task of modeling a complex JSON file descriptor structure. You will need to perform some clean up work after the generation, for example, setting the target id and static value of attributes, removing elements that are not required, and setting the mandatory attribute of elements where required.

The section below gives some guidance on how a JSON structured file descriptor is interpreted during run time.

You can specify a JSON file descriptor structure with objects and attributes that have missing values. If a specified non-mandatory object does not exist, AWM will skip it and continue parsing or generating the rest of the JSON document.

If a JSON object or attribute is specified as mandatory, AWM will enforce that it is present in the parsed JSON document or a property value is available when the JSON output is generated. If it is not, an error message is triggered and the parsing/generation process is stopped.

A file descriptor modelled in this way:

Could, for example, produce the following JSON payload at run time:

{
	"fields": {
		"summary": "No REST for the Wicked.",
		"issuetype": {
			"id": "Error"
		},
		"project": {
			"id": "10110"
		},
		"description": "Creation of an issue using IDs for projects and issue type."
	}
}

Examples

File Descriptor SCLM_FILE_ElelistMember