File Descriptor

A file descriptor describes a file and optionally, the structure of the file. The file can be located both in the Eclipse workspace or in the system to be attached.

The physical name (attribute Name_Physical) of the file does not have to be given in order to describe a file. This can be set by a tool output parameter at run time. If the physical name of the file already exists, a static value can be entered under this attribute. If only the structure of the file path has been specified, a dynamic path can be entered using dynamic references. See Variable References for more information.

A further feature of a file descriptor is the type. The “Workspace_File” type indicates files that should be saved in the workspace or that are to be read from the workspace.

Attribute	Type	Description
ID *	ID *	The ID of the file descriptor.
Name_Physical [O]	String	The physical name of the file under which the target system can find the file (file path + file name). Dynamic references are allowed.
PropDelimiter	String	The delimiter to be used for the interpretation of structured file content. Standard value: " " (Blank)
Structure	Selection	Describes the structure of the file. Permitted values: Unstructured (standard value) Table JSON
Type	Selection	The type of the file descriptor. This value specifies how the described file should be interpreted. Permitted values: InputStream Local_File Workspace_File (standard value)

Relationship	Cardinality	Description
Has_Property	0..*	Relationship to a Property. Property Values can be assigned to a file content, which enables the further editing of the content. This relationship can only be used for the description of structured files (table structure).
Has_Action	0..*	Relationship to an action descriptor. Used only if the file descriptor is of structure table and the table is part of a modeled dialog. In this case the actions appear in the context menu of the table items.

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 is expected to consist of values for the related properties separated by the property delimiter in the sequence of the property relation definition. At runtime the values in the file are mapped to the properties as specified in the file descriptor to property relations.

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 JSON File Descriptor structure 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 array or a JSON object 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 runtime and the property value is set by the value returned in the corresponding JSON attribute.

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 a 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 runtime:

{
	"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."
	}
}

If a JSON document is returned by a tool descriptor, AWM is able to create an element list from it. If the document describes more than one item, it must contain an array. AWM will attempt to create one element for each array value. If the JSON output contains other attributes outside the array object, the attributes' values will be added to each parsed element, provided they have been specified in the file descriptor and mapped to properties.

Note: JSON documents containing more than one array are currently not supported. AWM will still attempt to parse the document, but the result might not be as expected. Any JSON file descriptors with more than one array will cause a validation warning in the AWM model editor.

Examples

The file descriptor SVN_FD_Repository is used to return SVN repository locations:

Attribute	Value	Description
Essential:
ID	SVN_FD_Repository	Unique identifier for the file descriptor in this model.
Prop Delimiter	,	The property values returned in this structured file descriptor are separated with commas.
Structure	Table	A table structured file descriptor consists of a sequence of properties. Each line specifies the values for each property defined as a File Descriptor_Has_Property relationship.
Type	InputStream	The file content is provided in the form of an input stream.
Optional:
Name Physical	---	A Name Physical is not required for a file descriptor of type InputStream.

The file descriptor SVN_FD_WORK_LocalContent is used to model a file in the local workspace:

Attribute	Value	Description
Essential:
ID	SVN_FD_WORK_LocalContent	Unique identifier for the file descriptor in this model.
Prop Delimiter	---	Not applicable as it is an unstructured file descriptor.
Structure	Unstructured	The file has no internal structure.
Type	Workspace_File	The file descriptor represents a file within the Eclipse workspace.
Optional:
Name Physical	---	The physical name is not required as the file is returned as a file output parameter of a preceding tool.