AVEVA Ingestion Service API Request Parameters

For orchestration to understand how a particular file will be 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 it's orchestration should be carried out.

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

• The possible values for this parameter can be:

  Value	Description
  DE	For any 2D file that requires scraping using Data Extractor Gateway. For Example: PDF, DOC, DOCX, XLS, XLSX, PPT, and PPTX.
  AC2D	For any 2D file that requires scraping and conversion to a rendition using the AutoCAD Gateway. For Example: DWG, and DXF.
  MS2D	For any 2D file that requires scraping and conversion to a rendition using the Microstation Gateway. For Example: DGN
  AC3D	For any AutoCAD 3D file that requires scraping and conversion to a rendition using the 3D Gateway. For Example: DWG, and DXF.
  IFC	For any Industry Foundation Classes 3D file that requires scraping and conversion to a rendition using the 3D Gateway. For Example: IFC
  NAV	For any Navisworks 3D file that requires scraping and conversion to a rendition using the 3D Gateway. For Example: NWD
  CL	For an ISM class library. Only XML format for Class Library is currently supported by Register GW.
  Regi	For any 1D data file (register) that requires Regi GW processing. For Example: CSV, JSON, and XML
  Model	For any 3D model file that requires 3DVS processing.
  Custom	The file is a custom Gateway pattern file, homepage, or bootstrap XML that needs to be applied to the AIM-A environment.

  source

  This is an optional parameter that denotes the actual source system where the file originated from.

  publishOriginal

• This is a Boolean flag that instructs the orchestration to process the input file as it is. The file will not be 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, set to false by orchestration in all the cases.

  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 will be 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, set to true by orchestration in all the cases.

  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 will be scraped if the flag is set to true.

• Default value is false.

• This is a required parameter for every 2D and 3D file (that require 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 will be 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 will be added. This would represent a sub-system within an asset.

• More information about how Context Mapping works in AIM-A can be found here.

  fileName

• The name of the file to be uploaded into the AIM-A system.

  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 EIWMs for import.

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

  fileRevisionKey

• This parameter helps orchestration maintain a consistent data model when more than one revisions of a file are 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 will override documentIdentifier value and add an extra (unclassified) identifier for the document. Orchestration will then create 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 new Data Pipeline/Load reporting solution in AVEVA Connect. Documentation on how to use and enable this solution can be found here.

• 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 MS2D Gateway
  AC2D	Custom	The input file is a custom pattern file for AC2D Gateway
  AC3D	Custom	The input file is a custom AutoCAD pattern file for 3D Gateway
  IFC	Custom	The input file is a custom Industry Foundation Classes pattern file for 3D Gateway
  NAV	Custom	The input file is a custom Navisworks pattern file for 3D Gateway
  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

  Action

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

• For the 3D model deletion to function without error, two additional parameters must be specified:

  • fileName must be a CSV file (e.g., "fileName": "DeleteModels.csv")Known Types

  • target must be set to "Model".

  • The only accepted value for this parameter is:

    • delete: Exclusively for deleting 3D model files. Use lower case as this parameter is case sensitive.

  • More information about how 3D Model Deletion works, and the CSV file formatting, can be found here: Ingestion API 3D Model Deletion

• 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 a specific type of processing. For example, if an upload process accidentally forgets to pass Target parameter for a pdf file, the system will try to scrape and process the pdf file using 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 Register GW or DE GW processing. It defaults to Register GW, 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

• Video Files

• AutoCAD Files

• Industry Foundation Classed Files

• Navisworks Files

• Models

• Delete 3D Models

• 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

  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

  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"

  }]

  Video Files

Video files in .mp4, .mov, .avi, and .wmv formats must use the PublishOriginal flag for 2D Import. Other video formats are not currently supported.

The below examples are the required values for video files:

• publishOriginal = false

• publishRendition = false

• publishReference = true

  When uploaded to AIM, the video formats will have different behaviors :

• .mp4 files will render and can be playable within AIM

• .avi, .mov, .wmv will download from AIM and can be playable in a separate program.

  [{

  "PublishOriginal":true,

  "PublishRendition": false,

  "PublishReference": false,

  "DocumentIdentifier":"video",

  "FileRevisionKey":"2669133",

  "FileName":"large_video_file.mp4",

  "RegisterIdentifier":"samplevideos/mp4"

  }]

  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 (3DVS)

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-basemapping.xml",

  "drawingfile-ac2d-extractconfiguration.xml",

  "drawingfile-ac2d-loadconfiguration.xml",

  "drawingfile-ac2d-loadcsvconfiguration.xml",

  "drawingfile-ac2d-loadeiwmconfiguration.xml",

  "drawingfile-ac2d-loadsvgconfiguration.xml",

  "drawingfile-ac2d-patterns2d.xml",

  "drawingfile-ac2d-presentationmapping.xml",

  "drawingfile-ac2d-rescale2dunitsdef.xml",

  "drawingfile-ac2d-setlabel.xml",

  "drawingfile-ac2d-textmapping1.xml",

  "drawingfile-ac2d-textmapping2.xml",

  "drawingfile-ac2d-transformconfiguration.xml"

  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-extractconfiguration.xml",

  "drawingfile-ms2d-loadconfiguration.xml",

  "drawingfile-ms2d-loadcsvconfiguration.xml",

  "drawingfile-ms2d-loadeiwmconfiguration.xml",

  "drawingfile-ms2d-loadsvgconfiguration.xml",

  "drawingfile-ms2d-patterns2d.xml",

  "drawingfile-ms2d-rescale2dunitsdef.xml",

  "drawingfile-ms2d-setlabel.xml",

  "drawingfile-ms2d-textmapping.xml",

  "drawingfile-ms2d-transformconfiguration.xml",

  "drawingfile-ms2d-patternmappingregex-removehyphen.xml",

  "drawingfile-patternmappingregex.gct.xml",

  "drawingfile-presentationmapping.gct.xml"

  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"

Facets

[{

"target": "Custom",

"configId": "Facets",

"fileName": "FacetRegister.csv"

}]