Skip to content

MindConnect-NodeJS - Agent Development - MindConnect Agent Methods

MindConnect Agent implements the V3 of the MindConnect API .

The synchronous methods (IsOnBoarded, HasConfiguration, HasDataMapping...) are operating on agent state storage only.

The asynchronous methods (GetDataSourceConfiguration, BulkPostData...) are calling Insights Hub APIs.

IsOnBoarded

/**
 *
 * Check in the local storage if the agent is onboarded.
 *
 * * This is a local agent state storage setting only.
 *
 * @returns {boolean}
 * @memberof MindConnectAgent
 */
public IsOnBoarded(): boolean

HasDataSourceConfiguration

/**
 * Checks in the local storage if the agent has a data source configuration.
 *
 * * This is a local agent state storage setting only. 
 * * Call await GetDataSourceConfiguration() if you want to check if there is configuration in Insights Hub.
 *
 *
 * @returns {boolean}
 * @memberof MindConnectAgent
 */
public HasDataSourceConfiguration(): boolean

HasDataMappings

/**
 * Checks in the local storage if the agent has configured mappings.
 *
 * * This is a local agent state storage setting only. Insights Hub API is not called.
 * * Call await GetDataMappings() to check if the agent has configured mappings in the Insights Hub.
 *
 * @returns {boolean}
 * @memberof MindConnectAgent
 */
public HasDataMappings(): boolean

PutDataSourceConfiguration

/**
 * Stores the configuration in Insights Hub.
 *
 * By default the eTag parameter in the provided configuration is ignored, and the agent just updates the configuration every time the put method is stored
 * and automatically increases the eTag.
 * This is why its a good idea to check if the configuration was stored before the data was posted. If the ignoreEtag is set to false then the agent just uses
 * the eTag which was specified in the configuration. This might throw an "already stored" exception in Insights Hub.
 *
 * @param {DataSourceConfiguration} dataSourceConfiguration
 * @param {boolean} [ignoreEtag=true]
 * @returns {Promise<DataSourceConfiguration>}
 * @memberof MindConnectAgent
 */
public async PutDataSourceConfiguration(
    dataSourceConfiguration: DataSourceConfiguration,
    ignoreEtag: boolean = true
): Promise<DataSourceConfiguration>

GetDataSourceConfiguration

/**
 * Acquire DataSource Configuration and store it in the Agent Storage.
 *
 * @returns {Promise<DataSourceConfiguration>}
 *
 * @memberOf MindConnectAgent
 */
public async GetDataSourceConfiguration(): Promise<DataSourceConfiguration>

GetDataMappings

/**
 * Acquire the data mappings from Insights Hub and store them in the agent state storage.
 *
 * @returns {Promise<Array<Mapping>>}
 *
 * @memberOf MindConnectAgent
 */
public async GetDataMappings(): Promise<Array<Mapping>>

PutDataMappings

/**
 * Store data mappings in the Insights Hub and also in the local agent state storage.
 *
 * @param {Mapping[]} mappings
 * @returns {Promise<boolean>}
 *
 * @memberOf MindConnectAgent
 */
public async PutDataMappings(mappings: Mapping[]): Promise<boolean>

DeleteAllMappings

/**
 * Deletes all mappings from the agent
 *
 * @memberOf MindConnectAgent
 */
public async DeleteAllMappings();

PostEvent

/**
 * Posts the Events to the Exchange Endpoint
 *
 * @param {*} events
 * @param {Date} [timeStamp=new Date()]
 * @param {boolean} [validateModel=true]
 * @returns {Promise<boolean>}
 * @memberof MindConnectAgent
 */
public async PostEvent
        event: BaseEvent | CustomEvent,
        timeStamp: Date = new Date(),
        validateModel: boolean = true
    ): Promise<boolean>

Post Data

/**
 * Post Data Point Values to the Exchange Endpoint
 *
 * @param {DataPointValue[]} dataPoints
 * @param {Date} [timeStamp=new Date()]
 * @param {boolean} [validateModel=true] you can set this to false to speed up the things if your agent is working.
 * @returns {Promise<boolean>}
 * @memberof MindConnectAgent
 */
public async PostData(
    dataPoints: DataPointValue[],
    timeStamp: Date = new Date(),
    validateModel: boolean = true
): Promise<boolean>

BulkPostData

/**
 * Post Bulk Data Point Values to the Exchange Endpoint.
 *
 * @param {TimeStampedDataPoint[]} timeStampedDataPoints
 * @param {boolean} [validateModel=true]
 * @returns {Promise<boolean>}
 *
 * @memberOf MindConnectAgent
 */
public async BulkPostData(
    timeStampedDataPoints: TimeStampedDataPoint[],
    validateModel: boolean = true
): Promise<boolean>

UploadFile

/**
 * Upload file to Insights Hub IOTFileService
 *
 * * This method is used to upload the files to the Insights Hub.
 * * It supports standard and multipart upload which can be configured with the [optional.chunk] parameter.
 *
 * * The method will try to abort the multipart upload if an exception occurs.
 * * Multipart Upload is done in following steps:
 *     * start multipart upload
 *     * upload in parallel [optional.parallelUploadChunks] the file parts (retrying [optional.retry] times if configured)
 *     * uploading last chunk.
 *
 * @param {string} entityId - asset id or agent.ClientId() for agent
 * @param {string} filepath - Insights Hub file path
 * @param {(string | Buffer)} file - local path or Buffer
 * @param {fileUploadOptionalParameters} [optional] - optional parameters: enable chunking, define retries etc.
 * @param {(number | undefined)}[optional.part] multipart/upload part
 * @param {(Date | undefined)} [optional.timestamp] File timestamp in Insights Hub.
 * @param {(string | undefined)} [optional.description] Description in Insights Hub.
 * @param {(string | undefined)} [optional.type] Mime type in Insights Hub.
 * @param {(number | undefined)} [optional.chunkSize] chunkSize. It must be bigger than 5 MB. Default 8 MB.
 * @param {(number | undefined)} [optional.retry] Number of retries
 * @param {(Function | undefined)} [optional.logFunction] log functgion is called every time a retry happens.
 * @param {(Function | undefined)} [optional.verboseFunction] verboseLog function.
 * @param {(boolean | undefined)} [optional.chunk] Set to true to enable multipart uploads
 * @param {(number | undefined)} [optional.parallelUploads] max paralell uploads for parts (default: 3)
 * @param {(number | undefined)} [optional.ifMatch] The etag for the upload.
 * @returns {Promise<string>} - md5 hash of the file
 *
 * @memberOf MindConnectAgent
 *
 * @example await agent.UploadFile (agent.GetClientId(), "some/mindsphere/path/file.txt", "file.txt");
 * @example await agent.UploadFile (agent.GetClientId(), "some/other/path/10MB.bin", "bigFile.bin",{ chunked:true, retry:5 });
 */
public async UploadFile(
    entityId: string,
    filepath: string,
    file: string | Buffer,
    optional?: fileUploadOptionalParameters
): Promise<string>

GenerateDataSourceConfiguration

/**
 * Generates a Data Source Configuration for specified Asset Type
 *
 * you still have to generate the mappings (or use ConfigureAgentForAssetId method)
 *
 * @example
 * config = await agent.GenerateDataSourceConfiguration("castidev.Engine");
 *
 * @param {string} assetTypeId
 * @param {("NUMERICAL" | "DESCRIPTIVE")} [mode="DESCRIPTIVE"]
 * @returns {Promise<DataSourceConfiguration>}
 *
 * * NUMERICAL MODE will use names like CF0001 for configurationId , DS0001,DS0002,DS0003... for data source ids and DP0001, DP0002... for dataPointIds
 * * DESCRIPTIVE MODE will use names like CF-assetName for configurationId , DS-aspectName... for data source ids and DP-variableName for data PointIds (default)
 * @memberOf MindConnectAgent
 */
public async GenerateDataSourceConfiguration(
    assetTypeId: string,
    mode: "NUMERICAL" | "DESCRIPTIVE" = "DESCRIPTIVE"
): Promise<DataSourceConfiguration>

GenerateMappings

/**
 * Generate automatically the mappings for the specified target assetid
 *
 * !Important! this only works if you have created the data source coniguration automatically
 *
 * @example
 * config = await agent.GenerateDataSourceConfiguration("castidev.Engine");
 * await agent.PutDataSourceConfiguration(config);
 * const mappings = await agent.GenerateMappings(targetassetId);
 * await agent.PutDataMappings (mappings);
 *
 * @param {string} targetAssetId
 * @returns {Mapping[]}
 *
 * @memberOf MindConnectAgent
 */
public GenerateMappings(targetAssetId: string): Mapping[]

ConfigureAgentForAssetId

/**
 * This method can automatically create all necessary configurations and mappings for selected target asset id.
 *
 * * This method will automatically create all necessary configurations and mappings to start sending the data
 * * to an asset with selected assetid in Insights Hub
 *
 * @param {string} targetAssetId
 * @param {("NUMERICAL" | "DESCRIPTIVE")} mode
 * @param {boolean} [overwrite=true] ignore eTag will overwrite mappings and data source configuration
 *
 * * NUMERICAL MODE will use names like CF0001 for configurationId , DS0001,DS0002,DS0003... for data source ids and DP0001, DP0002... for dataPointIds
 * * DESCRIPTIVE MODE will use names like CF-assetName for configurationId , DS-aspectName... for data source ids and DP-variableName for data PointIds (default)
 * @memberOf MindConnectAgent
 */
public async ConfigureAgentForAssetId(
  targetAssetId: string,
  mode: "NUMERICAL" | "DESCRIPTIVE" = "DESCRIPTIVE",
  overwrite: boolean = true
)

SDK

/**
 * Insights Hub SDK using agent authentication
 *
 * ! important: not all APIs can be called with agent credentials, however Insights Hub is currently working on making this possible.
 *
 *  * Here is a list of some APIs which you can use:
 *
 *  * AssetManagementClient (Read Methods)
 *  * MindConnectApiClient
 *
 * @returns {MindSphereSdk}
 *
 * @memberOf MindConnectAgent
 */
public Sdk(): MindSphereSdk

GetValidator

/**
 * Ajv Validator (@see https://github.com/ajv-validator/ajv) for the data points. Validates if the data points array is only
 * containing dataPointIds which are configured in the agent configuration.
 *
 * @returns {ajv.ValidateFunction}
 *
 * @memberOf MindConnectAgent
 */
public GetValidator(): ajv.ValidateFunction

GetEventValidator

/**
 *
 * Ajv Validator (@see https://github.com/ajv-validator/ajv) for the events. Validates the syntax of the events.
 *
 * @returns {ajv.ValidateFunction}
 *
 * @memberOf MindConnectAgent
 */
public GetEventValidator(): ajv.ValidateFunction

GetMindConnectConfiguration

/**
 * Get local configuration from the agent state storage.
 *
 * * This is a local agent state storage setting only.  API is not called.
 *
 * @returns {IMindConnectConfiguration}
 *
 * @memberOf MindConnectAgent
 */
public GetMindConnectConfiguration(): IMindConnectConfiguration

Community

Connect and Collaborate with Industrial Professionals and Join the Community!

Click to load comments