---
title: "importFile"
slug: "api/session/operations/importfile"
sidebar:
  order: 160
---

<a id="ref-d4b6fdc657f9"></a>
<a id="ref-00117aed39a9"></a>
<a id="ref-5af3de880120"></a>

## Synopsis

```text
string importFile(SessionId sessionId,
    string url,
    string[]            attributes,
    ImportFileOptions*  options)
throws SessionServiceFault;
```

See also: [`SessionId`](/pCon/configuratorOnline/specs/api/session/types/sessionid#ref-02e397c8fdb4), [ImportFileOptions](/pCon/configuratorOnline/specs/api/session/types/importfileoptions#ref-08a1f833586f), [`SessionServiceFault`](/pCon/configuratorOnline/specs/api/session/faults/sessionservicefault#ref-30a5c7817f4a)

The `importFile` operation is used to import a file into the session. Importing a file means to copy the file into the session cache and compute an URI that can be used subsequently to identify  the imported file.

The `url` argument must be either an HTTP URL previously returned by the [getUploadURL](/pCon/configuratorOnline/specs/api/session/operations/getuploadurl#ref-5c73e4ded431) operation, or a FILE URL referencing a file within the local file system of the Online Configurator.

In case of a FILE URL, the `egr.eai.server.file_access` property of the session or server configuration file must be properly configured or the Online Configurator will reject access to the file.

The `attributes` argument is a list of attribute strings to be stored together with the file within the session cache. Each attribute string consists of a key and a value, separated by a single '=' (EQUALS SIGN, U+003D). White space around key and value are not stripped. Keys must consist of Basic Latin letters, digits  and '\_' (LOW LINE, SPACING UNDERSCORE, U+005F) only, and must not start with a digit. The format of values depends on the key.

There are the following well known attributes:

**`suffix`**

the file suffix, not including the leading dot (may be empty); If this attribute is not specified, the attribute is added automatically, using the suffix of the supported file. If specified, it takes precedence over the suffix of the imported file. In any case, the suffix is converted to lower case before stored in the session cache.

If the suffix is that of a recognized image file format (see below), or the file is identified as having a recognized image file format, both must match or the operation fails.

**`width, height`**

the width and height (in pixels) of raster image files; The value must be a decimal number greater than zero. If one is specified, both must be specified. A client should always specify these attributes for raster image files. If they are not specified, and the file is recognized as a raster image file, the operation tries to set these attributes. If it is unable to do so, the operation fails.

Recognized image file formats and corresponding suffixes are JPEG (suffixes "jpeg" and "jpg"), PNG (suffix "png"), GIF (suffix "gif"), BMP (suffix "bmp") and TIFF (suffixes "tiff" and "tif"). The operation should be able to determine width and height for all recognized image file formats except TIFF.

The `options` argument as well as individual options are optional. If not specified, the default value applies. Right now, the following option is defined:

`boolean *deleteAfterImport;`

If true, the file specified by the `url` argument is deleted once it has been successfully imported into the session cache. The default value of this option is `false`.

If the file is to be deleted, but the delete operation fails for some reason, a message is written to the log file but the `importFile` operation succeeds anyway.

If the operation succeeds, the return value is an URI with scheme `imp` that identifies the imported file. The URI may be used with the [resolveURIs](/pCon/configuratorOnline/specs/api/session/operations/resolveuris#ref-f7c4e7f011ab) operation to get an URL that can be used to access the cached file.

The operation fails if

- the specified session ID is not a valid string representation of an UUID or does not represent an open session

- the specified URL is not an HTTP or FILE URL or does not identify an accessible file

- one of the attribute strings does not start with a valid attribute key immediately followed by an EQUAL SIGN

- the file to be imported is empty

- the file is recognized as an raster image file and the `width` and/or `height` attributes are specified and have an invalid value, only one of them has been specified, or none of them has been specified and the operation is unable to determine their values

- the file format is not recognized by the suffix matches one of the suffixes of file formats the operation should be able to recognize

- the file format is recognized but the suffix (either explicitly specified derived from the file name) does not match the file format

- there was some input/output error reading the file or storing it in the session cache
