Ingestion API Request Parameters

For orchestration to understand how a specific file is processed, a set of pre-defined parameters must be passed from the API. These parameters are passed independently for each file in the API calls. The set of parameters in an API call either depends on the type of the file or the processing required for the file.

The following are the API parameters that are currently supported by the AIM Ingestion/Orchestration system:

• target

• source

• publishOriginal

• publishRendition

• publishReference

• documentIdentifier

• context

• fileName

• registerIdentifier

• fileRevisionKey

• configId

• action

Parameter Definitions

target

• This API parameter specifies which processing unit needs to act on the current file and how the orchestration must be carried out.

• Target is a mandatory API parameter and must be provided for any file.

• The possible values for this parameter are:

  Parameter Value	Description
  DE	For any 2D file that requires scraping using the Data Extractor gateway (PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX). For supported file types, see Limitations in AIM-A.
  AC2D	For any 2D file that requires scraping and conversion to a rendition using the Gateway for 2D Data (DWG, DXF). For supported file types, see Limitations in AIM-A.
  MS2D	For any 2D file that requires scraping and conversion to a rendition using the Gateway for 2D Data (DGN). For supported file types, see Limitations in AIM-A.
  AC3D	For any AutoCAD 3D files that require scraping and conversion to a rendition using the Gateway for 3D Data (e.g. DWG, DXF).
  IFC	For any Industry Foundation Classes 3D files that require scraping and conversion to a rendition using the Gateway for 3D Data (e.g. IFC).
  NAV	For any Navisworks 3D files that require scraping and conversion to a rendition using the Gateway for 3D Data (e.g. NWD).
  CL	For an ISM class library. Only XML format for a Class Library is currently supported by the Registers Gateway.
  Regi	For any 1D data file (register) that requires Registers Gateway processing (CSV, JSON, XML). For supported file types, see Limitations in AIM-A.
  Model	For any 3D model file that requires AIM-hybrid processing (RVM, ZGL). For supported file types, see Limitations in AIM-A.
  Custom	The file is a custom Gateway pattern file, homepage, bootstrap XML or Facet Register csv that needs to be applied to the AIM-A environment.
  AVEVAPID	For any 2D file that requires scraping and conversion to a rendition using the AutoCAD P&ID Extractor (e.g. DWG) in the Gateway for 2D Data. For supported file types, see Limitations in AIM-A.
  DEXPI	For any 2D file that requires scraping and conversion to a rendition using the DEXPI Extractor (e.g. DEXPI XML) in the Gateway for 2D Data. For supported file types, see Limitations in AIM-A.

source

This is an optional parameter that denotes the actual source system where the file originated from. This is not currently used by orchestration.

publishOriginal

• This is a Boolean flag that instructs the orchestration to process the input file as it is. The file is not converted into any rendition if the flag is set to true.

• Default value is false.

• This is a required parameter for every 2D file. Only applicable to files that are supported by the orchestration's Gateway capabilities.

• For 3D files, this should be set to "false".

publishRendition

• This is a Boolean flag that instructs the orchestration to convert the input file into its rendition (for example, DWG to SVG) before publishing the rendition to the AIM-A system. The file is converted into any rendition if the flag is set to true.

• Default value is false.

• This is a required parameter for every 2D file. Only applicable to files that are supported by the orchestration's Gateway capabilities.

• For 3D files, this should be set to "true".

publishReference

• This is a Boolean flag that instructs the orchestration to scrape references (both tags and documents) from the input file and publish these references to the AIM-A system. The file is scraped if the flag is set to true.

• Default value is false.

• This is a required parameter for every 2D and 3D file (that requires processing via their respective gateways). Only applicable to files that are supported by the orchestration's Gateway capabilities.

documentIdentifier

• This is a unique identifier for the document object in the AIM-A UI. The input file is associated to the document object with this identifier.

• This is a required parameter for every 2D file.

context

• If provided, this parameter represents the sub-context under which the file object is added. The sub-context represents a sub-system within an asset.

fileName

• The name of the file to be uploaded into the  AIM-A system. For supported file types, see Limitations in AIM-A.

registerIdentifier

• This is the ISM Class Library Register path to be used for data processing through Register Gateway.

• Every 1D file requires some instructions on how the information must be translated to an EIWM object and imported into AIM-A. RegisterIdentifier allows orchestration to look at the Class Library and find the rules it needs to apply to transform a 1D register into meaningful EIWM data for import.

• For example, if your InfoInterface hierarchy is System >> Register1, your registerIdentifier would be System/Register1.

fileRevisionKey

• This parameter helps the orchestration maintain a consistent data model when more than one revision of a file is loaded from the API or the document is updated. To make sure that we only show the latest revision of any file for any document, this value is used.

• When provided, fileRevisionKey overrides documentIdentifier value and add an extra (unclassified) identifier for the document. Orchestration then creates an association between the document object and the fileRevisionKey.

configId

• This parameter is used to specify what type of customization is being performed by the target "Custom".

• Any customization to target AIM environments can only be performed by tokens with the "AIM Configuration" role assigned to them. This is an administrative task so cannot be performed by account access tokens or service to service tokens. The role is available in the Data Pipeline/Load reporting solution in CONNECT.

• This property is used in conjunction with the target "Custom" and the possible values are listed below.

  ConfigId	Target	Description
  DE	Custom	The input file is a custom pattern file for DE Gateway
  MS2D	Custom	The input file is a custom pattern file for Gateway for 2D Data
  AC2D	Custom	The input file is a custom pattern file for Gateway for 2D Data
  AC3D	Custom	The input file is a custom AutoCAD pattern file for the Gateway for 3D Data
  IFC	Custom	The input file is a custom Industry Foundation Classes pattern file for the Gateway for 3D Data
  NAV	Custom	The input file is a custom Navisworks pattern file for the Gateway for 3D Data
  Homepage	Custom	The input file is a new Homepage for the respective asset
  Bootstrap	Custom	The input file is a bootstrap XML for the respective asset
  Facets	Custom	The input file is a csv file for the Facet Register
  AVEVAPID	Custom	The input file is a custom pattern file for AutoCAD gateway (e.g. DWG) for a AVEVA P&ID drawing file.
  DEXPI	Custom	The input file is a custom pattern file for DEXPI Gateway.

action

• This parameter is used exclusively for deleting 3D models.

• The possible value for this parameter is:

  Parameter Value	Description
  delete	For deleting 3D Models only. This is the only accepted value. The value must be all lowercase.

• This parameter requires two additional parameters that must be specified:

  • fileName must be a CSV file, for example: "fileName": "DeleteModels.csv".

  • target must be set to "Model".

• For more information on deleting 3D models, see Deleting Documents.

Known Types

• The orchestration has a fallback mechanism to decide the target for any input file, if it is already added into the system as a known type.

• For any file, if target is not specified by mistake, known types have been configured to default to a specific type of processing. For example, if an upload process accidentally forgets to pass Target parameter for a PDF file, the system scrapes and processes the PDF file using the DE gateway.

• For certain file types, there can be multiple valid processing units. Out of these, one is configured by default as a known type. If you want a different type of processing to be done for this file type, you need to make sure the target parameter is accordingly passed.

• For example, XLSX is a file type that may require the Registers Gateway or DE Gateway processing. It defaults to the Registers Gateway, so if you want an XLSX file to be scraped using DE, you need to specify target as DE in the API request.

• It is a recommended practice to always provide a target.

The following section provides sample sets of request parameters that must be provided for the specified file for orchestration to successfully process it.

• Class Library

• Registers

• Drawings

• MicroStation Files

• Documents

• AutoCAD Files

• DEXPI Files

• Industry Foundation Classes Files

• Navisworks Files

• Models

• Delete Documents

• Homepage

• Custom bootstrap

• Custom Gateway Configs - AC2D

• Custom Gateway Configs - MS2D

• Custom Gateway Configs - DE

• Custom Gateway Configs - AC3D

• Custom Gateway Configs - IFC

• Custom Gateway Configs - NAV

• Custom Gateway Configs - AVEVAPID

• Custom Gateway Configs - DEXPI

• Facets

Parameters for 1D Orchestration

Class Library

[{

    "target": "CL",

    "fileName": "clib.xml"

}]

Registers

[{

    "target": "Regi",

    "context": "CTX1",

    "fileName": "register1.csv",

    "registerIdentifier": "System/Register1"

}]

Parameters for 2D Orchestration

AVEVA P&ID files

[{

"target": "AVEVAPID",

"publishOriginal": false,

"publishRendition": true,

"publishReference": true,

"documentIdentifier": "AVEVAPID1",

"context": "CTX1",

"fileName": "drawing1.dwg",

"registerIdentifier": "System/References1",

"fileRevisionKey": "321456"

}]

DEXPI files

[{

"target": "DEXPI",

"publishOriginal": false,

"publishRendition": true,

"publishReference": true,

"documentIdentifier": "DEXPI1",

"context": "CTX1",

"fileName": "drawing1.xml",

"registerIdentifier": "System/References1",

"fileRevisionKey": "321456"

}]

Drawings

[{

"target": "AC2D",

"publishOriginal": false,

"publishRendition": true,

"publishReference": true,

"documentIdentifier": "DWG1",

"context": "CTX1",

"fileName": "drawing1.dwg",

"registerIdentifier": "System/References1",

"fileRevisionKey": "321456"

}]

MicroStation Files

[{

"target": "MS2D",

"publishOriginal": false,

"publishRendition": true,

"publishReference": true,

"documentIdentifier": "DGN1",

"context": "CTX1",

"fileName": "msd1.dgn",

"registerIdentifier": "System/References1",

"fileRevisionKey": "321456"

}]

Documents

[{

"target": "DE",

"publishOriginal": true,

"publishRendition": false,

"publishReference": true,

"documentIdentifier": "PDF1",

"context": "CTX1",

"fileName": "document1.pdf",

"registerIdentifier": "System/Documents1",

"fileRevisionKey": "321456"

}]

If you want to publish the scraped references for a file, you must pass the registerIdentifier for the respective ISM CL register.

You can provide any values for publishOriginal, publishRendition and publishReference flags. The above mentioned examples are the best suited values. For example, if you don't want to publish a DWG file but only its scraped references, you can set

• publishOriginal = false

• publishRendition = false

• publishReference = true

In case all three publish flags are set to false, orchestration does not process the file.

Parameters for 3D Orchestration (Gateway)

AutoCAD Files

[{

"target": "AC3D",

"publishOriginal": false,

"publishRendition": true,

"publishReference": true,

"context": "CTX1",

"fileName": "autocad1.dwg",

"registerIdentifier": "System/References1",

}]

Industry Foundation Classes Files

[{

"target": "IFC",

"publishOriginal": false,

"publishRendition": true,

"publishReference": true,

"context": "CTX1",

"fileName": "IndustryFoundationClasses1.ifc",

"registerIdentifier": "System/References1"

}]

Navisworks Files

[{

"target": "NAV",

"publishOriginal": false,

"publishRendition": true,

"publishReference": true,

"context": "CTX1",

"fileName": "Navisworks1.nwd",

"registerIdentifier": "System/References1"

}]

Parameters for 3D Orchestration (3DVis)

Models

[{

    "target": "Model",

    "context": "CTX1",

    "fileName": "model1.rvm"

}]

Delete 3D Models

[{

"target": "Model",

"fileName": "DeleteModel.csv",

"action": "delete"

}]

Parameters for Customization

Homepage

[{

    "target": "Custom",

"configId": "Homepage",

    "fileName": "homepage.html"

}]

Custom bootstrap

• Any custom bootstrap can be uploaded using this set of parameters.

• Roles cannot be covered as they require CONNECT Administration and cannot be automated entirely.

  [{

      "target": "Custom",

     "configId": "Bootstrap",

    "fileName": "Profiles.xml"

  }]

Custom Gateway Configs - AC2D

• Any AC2D configuration file can be uploaded using this set of parameters.

  [{

      "target": "Custom",

  "configId": "AC2D",

      "fileName": "Provide the file name that you want to process. See the allowed list of files below"

  }]

  AC2D configurable files:

  drawingfile-ac2d-patterns2d.xml
  drawingfile-ac2d-presentationmapping.xml
  drawingfile-ac2d-rescale2dunitsdef.xml
  drawingfile-ac2d-textmapping1.xml
  drawingfile-ac2d-textmapping2.xml

  For more information, see 2D Gateway Configuration.

Custom Gateway Configs - MS2D

• Any MS2D configuration file can be uploaded using this set of parameters.

  [{

      "target": "Custom",

  "configId": "MS2D",

      "fileName": "Provide the file name that you want to process. See the allowed list of files below"

  }]

  MS2D configurable files:

  drawingfile-ms2d-patterns2d.xml
  drawingfile-ms2d-presentationmapping.xml
  drawingfile-ms2d-rescale2dunitsdef.xml
  drawingfile-ms2d-textmapping.xml

  For more information, see 2D Gateway Configuration.

Custom Gateway Configs - DE

• Any DE configuration file can be uploaded using this set of parameters.

  [{

      "target": "Custom",

  "configId": "DE",

      "fileName": "Provide the file name that you want to process. See the allowed list of files below"

  }]

  DE configurable files:

  documentfile-patternmappingregex.dex.xml

Custom Gateway Configs - AC3D

• Any AC3D configuration file can be uploaded using this set of parameters.

  [{

  "target": "Custom",

  "configId": "AC3D",

  "fileName": "Provide the file name that you want to process. See the allowed list of files below"

  }]

  AC3D configurable files:

  modelfile-ac3d-basemapping.xml
  modelfile-ac3d-extractconfiguration.xml
  modelfile-ac3d-loadconfiguration.xml
  modelfile-ac3d-loadcsvconfiguration.xml
  modelfile-ac3d-loadeiwmconfiguration.xml
  modelfile-ac3d-loadzglconfiguration.xml
  modelfile-ac3d-presentationmapping.xml
  modelfile-ac3d-transformconfiguration.xml
  modelfile-ac3d-transformgeometry.xml

Custom Gateway Configs - IFC

• Any IFC configuration file can be uploaded using this set of parameters.

  [{

  "target": "Custom",

  "configId": "IFC",

  "fileName": "Provide the file name that you want to process. See the allowed list of files below"

  }]

  IFC configurable files:

  modelfile-ifc-basemapping.xml
  modelfile-ifc-extractconfiguration.xml
  modelfile-ifc-loadconfiguration.xml
  modelfile-ifc-loadcsvconfiguration.xml
  modelfile-ifc-loadeiwmconfiguration.xml
  modelfile-ifc-loadzglconfiguration.xml
  modelfile-ifc-presentationmapping.xml
  modelfile-ifc-propertysetmapping.xml
  modelfile-ifc-transformconfiguration.xml
  modelfile-ifc-transformgeometry.xml

Custom Gateway Configs - NAV

• Any NAV configuration file can be uploaded using this set of parameters.

  [{

  "target": "Custom",

  "configId": "NAV",

  "fileName": "Provide the file name that you want to process. See the allowed list of files below"

  }]

  NAV configurable files:

  modelfile-nav-basemapping.xml
  modelfile-nav-extractconfiguration.xml
  modelfile-nav-loadconfiguration.xml
  modelfile-nav-loadcsvconfiguration.xml
  modelfile-nav-loadeiwmconfiguration.xml
  modelfile-nav-loadzglconfiguration.xml
  modelfile-nav-presentationmapping.xml
  modelfile-nav-transformconfiguration.xml
  modelfile-nav-transformgeometry.xml

Custom Gateway Configs - AVEVAPID

• Any AVEVAPID configuration file can be uploaded using this set of parameters.

  [{

  "target": "Custom",

  "configId": "AVEVAPID",

  "fileName": "Provide the file name that you want to process. See the allowed list of files below"

  }]

  AVEVAPID configurable files:

  drawingfile-avevapid-patternmappingregex.xml
  drawingfile-avevapid-presentationmapping.xml
  drawingfile-avevapid-rescale2dunitsdef.xml
  drawingfile-avevapid-setlabel.xml
  drawingfile-avevapid-textmapping1.xml
  drawingfile-avevapid-textmapping2.xml

• For more information, see 2D Gateway Configuration.

Custom Gateway Configs - DEXPI

• Any DEXPI configuration file can be uploaded using this set of parameters.

  [{

  "target": "Custom",

  "configId": "DEXPI",

  "fileName": "Provide the file name that you want to process. See the allowed list of files below"

  }]

  DEXPI configurable files:

  drawingfile-dexpi-presentationmapping.xml
  drawingfile-dexpi-rescale2dunitsdef.xml
  drawingfile-dexpi-textmapping1.xml
  drawingfile-dexpi-textmapping2.xml

Facets

[{

"target": "Custom",

"configId": "Facets",

"fileName": "FacetRegister.csv"

}]