Revision history:

Introduced in QPR 2012.2

Last changed in QPR 2016.1

 

Imports elements from the source model to the currently open model.

 

Synopsis:

 

PGModel.ImportElements(Model, Parameters, out Log)

 

Parameters:

 

Model: Variant. Server model ID (integer), server model name (string), or a file name (string). File name can have an absolute or a relative path. If no path is given, function tries to load the import model from the current Modeling Client default path. Also server models require the path information to be visible in the case the model is identified by a name string, so for example \\ModelName or \\folder\ModelName are valid values.

Parameters: A semicolon-separated list. Supported parameters:

•ElementType: String. The symbol of the element type in the source model. If given, all elements of that type are imported.

•Hierarchy: String. The symbol of the custom hierarchy or the name of a fixed hierarchy in the source model. If given, all elements that belong to the specified hierarchy are imported. The following fixed hierarhies are supported: InformationItemHierarchy, ResourcePoolHierarchy, ResourceGroupHierarchy, NotesHierarchy, and OrganizationHierarchy.

•UpdateStructure: Boolean. Defines whether the hierarchy structure is updated or if the elements are imported as a flat list on the hierarchy root level. Default value is false (elements are imported as flat list). If true, the hierarchy structure is applied from the source model to the currently open model. If the hierarchy in the currently open model is not complete, it is constructed as well as possible. For example, if the source hierarchy contains a branch <e1>-<e1.1>-<e1.1.1>, and "e1.1" is missing from the currently open model, the branch in the currently open model will be <e1>-<e1.1.1>. The hierarchy definitions must be identical (for all matching element types) in both models, i.e. if an element type belongs to the hierarchy in both models, it must have the same "Part of branch" and "Node type" settings. If the hierarchy definitions are not identical, a conflict is reported and the structure is not updated. If the UpdateStructure parameter is not given, all new elements will be created to root level and deleting an element will move its child elements to root level, not to the deleted element's parent.

•Add: String. Defines the filter for adding elements. If defined, all elements that match the filter in the source model and that do not exist in the currently open model are added to the currently open model. If left empty, no elements are added to the currently open model. If an element is added and its behavior options define that it cannot exist without any instances, an instance of the element is created on the main diagram. In addition to custom elements, applies also to process steps and flows. Default value is empty. See the "<Filter>" entry below for filter syntax.

•Update: String. Defines the filter for updating elements. If defined, all elements that match the filter in the source model and that also exist in the currently open model are updated. If the filter is empty, no elements are updated. Instances or their (graphical) properties are not updated. If the element in the currently open model has custom attributes that do not exist in the source model, their values are left untouched. Default value is empty. See the "<Filter>" entry below for filter syntax.

•Delete: String. Defines the filter for deleting elements. If defined, all elements that match the filter in the source model are deleted from the currently open model. If the filter is empty, no elements are deleted. If a special filter "missing" is used, all elements that exist in the target model but do not exist in the source model are deleted. Default value is empty. See the "<Filter>" entry below for filter syntax.

•SourceModelAttribute: String, or if textual: FullID. Defines an external model attribute type. If given, the import source model is set as the external model custom attribute value in all elements that are added to the currently open model. If the attribute is cardinality N, and the attribute already had values in the source model, those values are preserved and a new value is added to the attribute. If this parameter is given, the attribute value is left unchanged in the currently open model in the "update" operation, i.e. its value is not copied from the source model element.

•ImportedObjectId: String. Defines a number attribute type. If given and the attribute exists in the target element, the ID of the source element is set as the attribute value in the target element.  If the attribute is cardinality N and the attribute already had values in the source model, those values are preserved and a new value is added to the attribute. If this parameter is given, the attribute value is left unchanged in the target model in the "update" operation, i.e. its value is not copied from the source model element.

•SetAttribute: String. Defines an attribute name and value, separated by a colon (i.e. <attribute>:<value>). If this parameter is given, and if a new element has been imported and the attribute exists in the element, the value of the attribute is set to the given value. There can be multiple SetAttribute parameters. This parameter does not create new custom attributes, i.e. the value is set to only those elements that already have the corresponding custom attribute. The SetAttribute parameter can be used multiple times to set values for many custom attributes in the same call.

•<Filter>: All | Missing | <attribute filter>:

oAll: Matches with all elements. Can be used with the Update parameter.

oMissing: Matches elements that exist in one model but do not exist in the other model. Can be used with the Add and Delete parameters.

o<attribute filter>: If the attribute filter expression returns a non-zero value (i.e. boolean true) the filter matches to the element. Possible operators include <, <=, >, >=, =, <>, NOT, AND, OR, XOR, +, -, /, *, MOD, DIV, ^. The evaluation order can be defined with parentheses. Date time uses floating point values, and they can be converted to working format with EncodeDate, DateTime, and Time functions explained in the QPR Metrics - User's Guide 'Built-in Functions' topic. Property names can be used to refer to property values. Numbers, texts, booleans, enumerations, date times, and relations are supported. In case of a relation, the name of the related element is returned. If the element does not have the property or the value, then the filter does not match. Format is the same as used in GetProperty/GetProperties/SetProperty API functions. String constants can be defined by quoting them. If the filter references a property that is not found from the element, the evaluation result is false.

•GenerateChangeList: Boolean. If true, the out Log array is generated on all imported elements. The description is empty for those elements that have no conflict. Default value is false.

•FindRelationTargets: <Comma-separated list of relation attributes>. If attribute name contains spaces then it must be in quotes (e.g. "Elem1 to Elem2"). To refer to a single relation attribute in an attribute set, use dot as a separator (e.g. set1.relation1). When elements are imported, the values of the listed relation attributes are used as element symbols, and the import tries to find and set the relations using the symbol.

•ExcludeAttributes: <Comma-separated list of attributes> If attribute name contains spaces then it must be in quotes (e.g. "Elem1 to Elem2"). When referring to attribute sets, all attributes in the attribute set are excluded. To exclude a single attribute in an attribute set, use dot as a separator (e.g. set1.attribute1). The values of the listed attributes are not set to new or updated elements when elements are imported.

out Log: Variant array. Log is a two-dimensional variant array containing one entry for each conflict encountered in import. Each entry contains the following information:

oElement ID in the currently open model. Integer.

oElement ID in the source model. Integer.

oElement name. String.

oConflict code. Integer.

oConflict description. String.

 

Note: If an element matches both add and delete filter, the element will first be deleted and then added from the model. So, in effect, it will be updated. Note, that this way you can change the meta-type of the element but will also lose any relations to the element.

 

Note: Elements, element types, and custom hierarchies are always matched by their symbols. Attribute types are matched by their name and type.

 

Note: ElementType and Hierarchy parameters cannot be used at the same time. If they are used at the same time, the function fails and returns RV_INVALID_PARAMETER.

 

Note: If there are attribute relations between the imported elements, those relations remain after the import.

 

Required Rights:

 

System or model administrator.

 

Return Values:

Below are listed the return values that this function can return:

 

RV_SUCCESS

RV_APPLICATION_QUIT_CALLED

RV_MODEL_NOT_OPEN

RV_NOT_ENOUGH_RIGHTS

RV_MODEL_DOES_NOT_EXIST

RV_UNSUPPORTED_FILE_TYPE

RV_CANNOT_OPEN_MODEL

RV_LOGIN_FAILED

RV_UNKNOWN_ERROR

RV_MODEL_CANNOT_BE_OPENED_WITH_CURRENT_EDITION

RV_NO_LICENSE_FOR_MODEL

RV_INVALID_PARAMETER

RV_ELEMENT_TYPE_NOT_FOUND

RV_HIERARCHY_NOT_FOUND

RV_FUNCTION_CANNOT_BE_USED_IN_VALIDATION_SCRIPT

RV_CANNOT_IMPORT_FROM_DEMO_MODEL

 

Example Procedure:

 

Sub main()

 Dim i, iResult, aoLog, sLog

 iResult = PGModel.ImportElements("G:\temp\305249\infolibrary.qprdam", "Hierarchy=InformationItemHierarchy;UpdateStructure=True;Add=Missing;Update=All;Delete=Missing", aoLog)

 If iResult <> 0 Then

   MsgBox "ImportElements failed: " + PGApplication.GetErrorMessage(iResult)

 ElseIf Not (IsEmpty(aoLog) or IsNull(aoLog)) Then

   sLog = ""

   For i = 0 To ubound(aoLog)

     sLog = sLog + "Element: """ + aoLog(i,2) + """, Symbol: """ + aoLog(i,3) + """ - " + aoLog(i,4) + vbCrLf

   Next

   MsgBox "Conflicts:" + vbCrLf + sLog

 Else

   MsgBox "ImportElements successful"

 End If

End Sub