Web API: Importfile: Difference between revisions

From QPR ProcessAnalyzer Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(11 intermediate revisions by the same user not shown)
Line 1: Line 1:
The '''importfile''' operation imports data from a file to QPR ProcessAnalyzer [[QPR_ProcessAnalyzer_Project_Workspace#Managing_Datatables|datatable]]. Only UTF-8 type of data is supported, so file needs to be converted into UTF-8. Invalid characters are still supported by the import. In case invalid characters are imported, either a new import needs to be made with a corrected file, or the data needs to be cleaned using a script.
The '''importfile''' operation imports data from a text file to a [[QPR_ProcessAnalyzer_Project_Workspace#Managing_Datatables|datatable]].
 
UTF-8 is the only supported character encoding, so the file needs to be converted into UTF-8 for the import. In case some other character encoding is used, it might lead to invalid characters, which are still imported. In case invalid characters are imported, either a new import needs to be made with a corrected file, or the data needs to be cleaned using a script.


HTTP request header '''Authorization''' with value '''Bearer <access token>''' needs to be in place to identify the session.  
HTTP request header '''Authorization''' with value '''Bearer <access token>''' needs to be in place to identify the session.  


<pre>
<pre>
Url: POST /api/importfile?param1=value1&param2=value2&param3=value3
Url: POST qprpa/api/importfile?param1=value1&param2=value2&param3=value3
Content-Type: multipart/form-data
Content-Type: multipart/form-data
Body: <file contents>
Body: <file contents>
</pre>
</pre>


Following parameters can be defined:
Following query parameters can be defined:
* '''fileType''' (string): Defines content format of the imported file. Options are '''csv''', '''pacm''' and '''xes'''.
* '''fileType''' (string): Defines content format of the imported file. Options are '''csv''', '''pacm''' and '''xes'''.
* '''importMode''' (string): Defines what kind of data is imported. Options are '''datatable''', '''events''' and '''cases'''. Needed when fileType=csv.
* '''objectId''' (integer): Datatable id. Needed when importing data to an existing datatable.
* '''objectId''' (integer): Model or datatable id. Needed when importing data to an existing model or a datatable.
* '''append''' (boolean): When true, the possible previous data in the destination datatable is preserved. When false, previous data is removed and also datatable columns are deleted.
* '''matchByColumns''': JSON array of datatable columns that are used to match the imported rows as follows: If a matching row is found, that existing row is updated (with columns not listed by this setting). In other case, a new row is created to the datatable. By default, no matching columns are defined, so all data is imported as new rows.
* '''csvDelimiter''' (string): Column delimiter character for the csv format.
* '''csvDelimiter''' (string): Column delimiter character for the csv format.
* '''csvTimeFormat''' (string): Date format to use when interpreting date values for the csv format.
* '''csvQualifier''' (string): Character used to enclose strings for the csv format.
* '''csvQualifier''' (string): Character used to enclose strings for the csv format.
* '''csvTimeFormat''' (string): Date format to use when interpreting date values for the csv format.
* '''csvStartImportFromLine''' (integer): The column name row in the csv file.
* '''csvStartImportFromLine''' (integer): The column name row in the csv file.
* '''append''' (boolean): When true, the possible previous data in the destination datatable is preserved. When false, previous data is removed and also datatable columns are deleted.
* '''isCompressed''' (boolean): When true, the file is compressed using gzip format. Only csv and xes files can be provided as compressed (pacm file is already a gzip file).
* '''isCompressed''' (boolean): When true, the file is compressed using gzip format. Only csv and xes files can be provided as compressed (pacm file is already a gzip file).
When importing to an existing datatable, data needs to be converted into each column's datatype. Conversions are made for each datatype as follows:
* String: No conversion needed.
* Integer: Convert digits to corresponding to integer.
* Float: Convert to float using period (.) as the decimal separator.
* DateTime: Convert to date using the provided ''csvTimeFormat''.
* Boolean: Convert to boolean with ''true'' as true value and ''false'' as false value.
* Duration: Convert to integer and interpret the value as ticks (10000 ticks is 1 millisecond).
* Empty data is imported as ''null'' values (applies for all datatypes).
If conversion is not possible, an error is given and the import stops. Note that part of the data may have been imported successfully to the datatable.


[[Category: QPR ProcessAnalyzer]]
[[Category: QPR ProcessAnalyzer]]

Latest revision as of 10:05, 16 February 2022

The importfile operation imports data from a text file to a datatable.

UTF-8 is the only supported character encoding, so the file needs to be converted into UTF-8 for the import. In case some other character encoding is used, it might lead to invalid characters, which are still imported. In case invalid characters are imported, either a new import needs to be made with a corrected file, or the data needs to be cleaned using a script.

HTTP request header Authorization with value Bearer <access token> needs to be in place to identify the session.

Url: POST qprpa/api/importfile?param1=value1&param2=value2&param3=value3
Content-Type: multipart/form-data
Body: <file contents>

Following query parameters can be defined:

  • fileType (string): Defines content format of the imported file. Options are csv, pacm and xes.
  • objectId (integer): Datatable id. Needed when importing data to an existing datatable.
  • append (boolean): When true, the possible previous data in the destination datatable is preserved. When false, previous data is removed and also datatable columns are deleted.
  • matchByColumns: JSON array of datatable columns that are used to match the imported rows as follows: If a matching row is found, that existing row is updated (with columns not listed by this setting). In other case, a new row is created to the datatable. By default, no matching columns are defined, so all data is imported as new rows.
  • csvDelimiter (string): Column delimiter character for the csv format.
  • csvTimeFormat (string): Date format to use when interpreting date values for the csv format.
  • csvQualifier (string): Character used to enclose strings for the csv format.
  • csvStartImportFromLine (integer): The column name row in the csv file.
  • isCompressed (boolean): When true, the file is compressed using gzip format. Only csv and xes files can be provided as compressed (pacm file is already a gzip file).

When importing to an existing datatable, data needs to be converted into each column's datatype. Conversions are made for each datatype as follows:

  • String: No conversion needed.
  • Integer: Convert digits to corresponding to integer.
  • Float: Convert to float using period (.) as the decimal separator.
  • DateTime: Convert to date using the provided csvTimeFormat.
  • Boolean: Convert to boolean with true as true value and false as false value.
  • Duration: Convert to integer and interpret the value as ticks (10000 ticks is 1 millisecond).
  • Empty data is imported as null values (applies for all datatypes).

If conversion is not possible, an error is given and the import stops. Note that part of the data may have been imported successfully to the datatable.