Import Files

Import files contain a set of import commands that are to be processed in the order in which they appear.

There might exist a precedence between inter-related commands. For instance, when creating a company MyCompany and a person MyPerson that belongs to that company, the company command should be specified before the person command.

An import command is a single text line comprising the following items:


  • an operation, indicating the type of operation to be performed, e.g. creating/updating an object or adding/removing an item from another object
  • a keyword, indicating the type of the command, e.g. company, person
  • a list of values identifying the contents of the command (object attributes, related objects identifiers, etc.); these values are separated by a customizable character, and a special "null" string can be used to reference an unset value; the exact number and type of these values is command-dependent and is listed in the section "Import File Syntax".

Standard commands

Creation and update operations are referred to as standard commands and are prefixed by the * character. For example, the standard command:

*CTX

creates a context.

Modifier Commands

Commands may be related from a syntax point of view. That is, a particular command may require to be specified after another. These commands, referred to as modifier commands, are prefixed by the + or - characters.

For example, the command:

+CTX

making it possible to assign a particular context to a person must be specified after a *PERSON command corresponding to the person definition it applies to.

Several modifier commands might exist that apply to separate parent commands. For instance, the command:

-ALL

applies to both *PERSON and *CTX.

Blank and empty lines, as well as comment lines (lines beginning with a double slash //) are ignored by the command parser.

The result of an execution of an import can be checked by the exit code of the batch program (0 when successful, non-zero otherwise) as well as the report lines that are displayed for processed commands (comment and empty/blank lines are ignored), for example:

15 business unit Admin [ OK ] Created

16 [*ERROR*] Could not save

Import File Syntax

Note the following:


  • command values are listed using the following format: <attribute name>; they are replaced with actual attribute values in import files
  • when relevant, optional attributes are listed between square brackets (e.g. [<optional attribute>]); they may be skipped in import files, in which case the null character (e.g. $) must be used instead
  • when relevant, the authorized values of attributes are listed between brackets using the following format, for example: <attribute name>={value1|value2}.

Compatibility

New commands in this release are only made available when using the corresponding import grammar, which is achieved by setting import version number to V6R2009-1.0 (or 206) using command *VERSION.

Trying to use V6R2012x (or 208) commands with earlier import grammars will trigger an error.

Users that were created using earlier versions of the import batch can not be used as is to execute import/export batches using this release. You must first set them as VPLM administrators explicitly, using dedicated command +ADMIN.

Here is the list of all the commands supported by the import batch. They fall into two categories: global commands and P&O commands.

Global Commands

Command Purpose Default Description
*VERSION <number> Set import file version number N/A

File version is used by the import engine to determine the syntax (specific to a release) to be used when processing a file. If a particular command is specified in an import file containing a version that doesn't support that command, an error will be triggered. File version is mandatory.

A file version is an integer string value standing for a V5 release number. The format of version numbers was modified so as to support new official release numbers (e.g. V6R2008-2.0). Older version numbers (e.g. 204) are still supported even though the new format should be used instead whenever possible. Available version numbers and their corresponding release are as follows:


  • 16: V5R16
  • 202: V5R2.2
  • 203: V5R2.3
  • V6R2008-1.0, 204
  • V6R2008-2.0, 205
  • V6R2009-1.0, 206

Note: since it has a direct impact on command parsing, the *VERSION command should be located at the beginning of import files, prior to any other object-specific command.
*SEPARATOR <character> Set attribute separator character ; Since it has a direct impact on command parsing, command *SEPARATOR should be located at the beginning of import files, prior to any other object-specific command.
*NULL <character> set "unset" attribute representation string $ Since it has a direct impact on command parsing, command *NULL should be located at the beginning of import files, prior to any other object-specific command.

P&O Commands

Command Purpose Default Description
*COMPANY <id>; [<parent id>]; [<description> Create/update a company Object Company is used to model top-level companies and their subsidiaries

<id>: company identifier

<parent id>: optional parent company identifier; if not null, the current company object is implicitly a subsidiary of that parent company

<description>: optional company description
*BUSINESSUNIT <id>; <parent id>; [<description>] Create/update a business unit Object Business Unit is used to model company business unit structures.

Note: Modification of a parent organization is supported neither in batch import mode nor GUI mode

<id>: business unit identifier

<parent id>: parent identifier; the parent of a business unit may either be a company or another business unit

<description>: optional business unit description
*DEPARTMENT <id>; <parent id>; [<description>] Create/update a department Object Department is used to model company departments

<id>: department identifier

<parent id>: parent company or business unit identifier

<description>: optional department description
+MEMBER <person id> Declare a person as a member of the previous organization A person can be made a member of one or several organizations (i.e. a company, business unit or department).

<person id>: employee identifier

Note: modifier command +MEMBER, applied to commands *COMPANY, *BUSINESSUNIT or *DEPARTMENT, is equivalent to modifier command +MEMBER applied to command *PERSON.

A newly created person is automatically made a member of his/her employing company.
-MEMBER <person id> Undeclare a person as a member of the previous organization The membership of a person can be removed for any particular organization (i.e. a company, business unit or department).

<person id>: employee identifier

Note: modifier command -MEMBER, applied to commands *BUSINESSUNIT or *DEPARTMENT, is equivalent to modifier command -MEMBER applied to command *PERSON.

*PRJ <id>; [<parent id>]; [<description>] Create/update a project Object Project is used to model company projects (e.g. a new sedan or private jet); it is one of the three characteristics of object Context, and any security access that may be associated to it is automatically inherited by users when connecting to a PLM provider.

<id>: project identifier

<parent id>: optional parent project identifier; security data is inherited from parent to child projects

<description>: optional project description.
*ROLE <id>; [<parent id>]; [<description>] Create/update a role Object Role is used to model the role (e.g. "Designer", "Manager") of a person in the PLM ecosystem; it is one of the three characteristics of contexts, and any security data that may be associated to it is automatically inherited by users when connecting to a PLM provider.

<id>: role identifier

<parent id>: optional parent role identifier; security data is inherited from parent to child roles

<description>: optional role description.
+ORG <name> Add an applicable organization to a role.  

<name> : Name of the organization object the role is made applicable to.

A warning is issued if the role is already applicable to the organization.
-ORG <name> Removes an applicable organization from a role.  

<name> : Name of the organization object the role is made applicable to.

A warning is issued if the role is not applicable to the organization.
-ALLORG Removes all applicable organizations from a role.   Comments: A warning is issued if the role has no applicable organization.
*PERSON <id>; <company id> Create/update a person Object Person is used to model human individuals that interact in the PLM environment; persons are the entry point of PLM applications.

<id>: person identifier

<company id>: identifier of company that employs the person.
+PASSWORD [<value>] Sets the password of the previous person A person may have a particular password that is necessary to connect to VPLM and ENOVIA V6 applications <value>: optional password string; if left unset, the person will be able to connect without specifying a password
+MEMBER <organization id> Declare the previous person as the member of an organization A person can be made a member of one or several business organizations (i.e. a company, a business unit or a department).

<organization id>: organization identifier.

Note: modifier command +MEMBER, applied to command *PERSON, is equivalent to modifier command +MEMBER applied to commands *COMPANY, *BUSINESSUNIT or *DEPARTMENT

Note: a newly created person is automatically made a member of his/her employing company.
-MEMBER <organization id> Undeclare the previous person as a member of an organization. The membership of a person can be removed for any particular organization (i.e. a company, a business unit or a department).

<organization id>: organization identifier.

Note: modifier command -MEMBER, applied to command *PERSON, is equivalent to modifier command -MEMBER applied to commands *COMPANY, *BUSINESSUNIT or *DEPARTMENT.
+CTX <context id> Assign a security context to the previous person A person may be assigned several contexts by the VPLM administrator, depending on the role (e.g. designer), working project (e.g. project "New Car") or operational organization (e.g. "Body in white"). When connecting to a PLM provider the user must select one particular security context among those he/she is assigned: this context will be used to initialize ownership attributes when creating PLM data; a user automatically inherits all security accesses that are associated to all his/her assigned security context during the PLM session.

<context id>: security context identifier

Note: modifier command +CTX, applied to command *PERSON, is equivalent to modifier command +PERSON applied to command *CTX.
-CTX <context id> Unassign a security context from the previous person When unassigning a context from a person, it is made unavailable from the latter and can no longer be selected when connecting to a PLM provider; all security accesses associated to that context are no more inherited by the user.

<context id>: context identifier

Note: modifier command -CTX, applied to command *PERSON, is equivalent to modifier command -PERSON applied to command *CTX.
-ALL Unassign all contexts from the previous person

N/A

When unassigning all contexts from a person, they are made unavailable from the latter and can no longer be selected when connecting to a PLM provider; all security accesses associated to these contexts are no more inherited by the user.

Modifier command -ALL, applied to command *PERSON, is equivalent to modifier command -ALL applied to command *CTX.
+ACTIVE Activate the previous person

A person must be active in order to connect to VPLM applications.

By default, persons are set active when created using the import batch, so it is not necessary to modify older import files in order to add +ACTIVE commands.

Note: since the default for persons is to be active, the +ACTIVE command is not managed by the export batch, i.e. will not be specified when exporting active users.

  
+INACTIVE Deactivate the previous person

An inactive person is not authorized to connect to VPLM applications.

Note: persons can be authored using the import batch even when inactive; they can also be exported.

The +INACTIVE command is specified whenever appropriate by the export batch.

  
+ADMIN Set the previous person as a VPLM administrator

A person can be made a VPLM administrator so it can be used to run import/export batches.

Performing P&O and security authoring requires particular VPLM administration privileges that must be specify directly at user level, and are thus independent from the security contexts that are possibly assigned to the user.

As a consequence, a user that is not set as administrator will not be authorized to perform administration tasks, even if the user is assigned to context VPLMAdmin.MyCompany.Default, and must explicitly be set as administrator using the +ADMIN command.

In earlier releases, only the administration user created during the installation could be used to run import/export batches. Note: the +ADMIN command is specified whenever appropriate by the export batch.

  
-ADMIN Unset the previous person as a VPLM administrator

A person can be unset as VPLM administrator so it cannot be used to run import/export batches anymore.

Since by default persons are not VPLM administrators, the -ADMIN command is not managed by the export batch, i.e. will not be specified when exporting regular users.

  
!PERSON <id> Delete a person

This command permanently removes the specified Person object, removing all possible references to other P&O or Security objects (e.g. context assignments, policies, etc.).

Note: this command does not handle possible references to the Person object in VPLM data. For instance, if that person is the owner of VPLM application data, the operation will fail.

In that case, it is the responsibility of the data owner, the VPLM administrator, or any other VPLM user granted sufficient privileges, to transfer the data to another user prior to deleting the person.

 <id>: person identifier
*CTX <role id>; <organization id>; <project id>; [<description>] Create/update a security context

Object Security Context is used to model a work assignment, i.e. the capability for a person to work in the PLM environment using a particular role (e.g. as a designer), in a particular project (e.g. project "New car") and for particular operational organization (e.g. "Body in white").

It is the entry point, along with the user, of the connection to a PLM provider; it can be associated security accesses that are automatically inherited by assigned users.

<role id>: role identifier; security data is inherited from roles to contexts;

<organization id>: business unit or department identifier - a company can not be used as an organization component when defining a security context; security data is inherited from organizations to contexts;

<project id>: project identifier; security data is inherited from projects to contexts;

<description>: optional context description.

+PERSON <person id> Assign the previous context to a person A context may be assigned to several persons by the VPLM administrator; these persons can then choose from their assigned contexts when connecting to a PLM provider; the user inherits all security accesses that are associated the contexts

<person id>: person identifier

Note: modifier command +PERSON, applied to command *CTX, is equivalent to modifier command +CTX applied to command *PERSON.
-PERSON <person id> Unassign the previous context from a person When unassigning a context from a person, it is made unavailable from the latter and can no longer be selected when connecting to a PLM provider; all security accesses associated to that context are no more inherited by the user

<person id>: person identifier

Note: modifier command -PERSON, applied to command *CTX, is equivalent to modifier command -CTX applied to command *PERSON.
-ALL Unassign the previous context from all persons

N/A

When unassigning a context from all persons, it is made unavailable from the latter and can no longer be selected when connecting to a PLM provider; all security accesses associated to these contexts are no more inherited by the user

The modifier command -ALL, applied to command *CTX, is equivalent to modifier command -ALL applied to command *PERSON.

+ATTRIBUTE <name>;

<value>

 Set an attribute value The business attributes of P&O objects can be set thanks to this command

<name>: attribute name; only business attributes may be specified (basic attribute are managed directly in standard commands)

<value>: attribute value.

Note: multi-valuated attributes are not supported in this release (see also Limitation #3).

Note: this command only applies to P&O objects modelled as business objects (see Limitation #6) for details.

-ATTRIBUTE <name> Unset an attribute value The business attributes of P&O objects can be unset thanks to this command

<name>: attribute name; only business attributes may be specified.

Note: multi-valuated attributes are not supported in this release (see also Limitation #3).

Note: this command only applies to P&O objects modelled as business objects (see Limitation #6) for details

It is not necessary to specify all null characters in import command lines when values need not be specified, provided there are no other subsequent mandatory attributes. For instance, you can define the following person command:

*COMPANY MyCompany; MyParentCompany

instead of:

*COMPANY MyCompany;MyParentCompany;$;$;$;$;$;$;$

However, the following:

*PERSON MyPerson

is illegal, because attribute "company" of command *PERSON is mandatory (i.e. a person must be attached to a company).