External Agent COM API Reference Guide › API Interfaces: Applying Policy and Generating CA DataMinder Events › COM Object: WGNRDILib::WgnActiveImportConnector › Interface IWgnActiveImportConnector › Method ImportObject

Method ImportObject

This is a synchronous call to supply a message to CA DataMinder and to return Smart Tags, as a result of analysis against policy. This may lead to an event corresponding to the message being saved in the CA DataMinder database, depending on how policy is configured.

Note:  Asynchronous calls are covered by the ImportObjectAsync() method.

HRESULT ImportObject(
    [in]         WGN_IMPORTOBJ_TYPE       objectType,
    [in]         WGN_IMPORTOBJ_FORMAT     objectFormat,
    [in]         WGN_IMPORTOBJ_TRANSPORT  objectTransport,
    [in]         VARIANT                  objectData,
    [in, unique] LPOLESTR                 messageId,  // OPTIONAL
    [in]         DWORD                    importSource,
    [in, unique] LPOLESTR                 xmlMessageAttributes,  // OPTIONAL
    [in]         DWORD                    eventSizeHintBytes,
    [in]         BOOL                     allowDeferredCompletion,
    [out]        IWgnImportConnectorResult  **results
    );

Where:

objectType

Specifies the type of object to import (e-mail or IM). For details, see the typedef WGN_IMPORTOBJ_TYPE.

objectFormat

Specifies the format of the object to import. For details, see the typedef WGN_IMPORTOBJ_FORMAT.

objectTransport

Specifies the method used to transfer data to the External Agent. For details, see the typedef WGN_IMPORTOBJ_TRANSPORT.

objectData

Specifies the source data being imported.

messageID

Is a string that specifies the unique identifier of the message within the archive.

This parameter is optional. It can be NULL if no link is to be made to a remote archive or if allowDeferredCompletion is TRUE, in which case the client will supply the messageID when committing the transaction.

This parameter must be set to NULL if and only if the importSource parameter is set to WGN_ACTIVEIMPORTSOURCE_NONE.

importSource

Is a fixed integer that identifies the source archive. If there is no link to a remote archive, it is WGN_ACTIVEIMPORTSOURCE_NONE.

xmlMessageAttributes

Optional XML containing additional metadata for the message.

allowDeferredCompletion

If set to TRUE, this indicates that an event must not be committed to the CA DataMinder database until the client has processed the results of the analysis. This enables the client to:

• Use Smart Tags to determine whether or not the message is to be archived. In turn, this determines whether CA DataMinder must save a corresponding event in the CMS database.
• Postpone allocating a unique ID for the message. This is useful in situation a. above, where the unique message ID is not known until the message is actually archived.
• Postpone identifying the importSource archive identifier. This allows the caller to choose which archive system to send the message to (where multiple systems are used), based on the content of the Smart Tags.

When using deferred completion, the caller is able to do all of the above via the IWgnImportConnectorDeferredCompletion interface. This is:

• Either obtained from the IWgnImportConnectorResult interface.
• Or supplied to the client via the IWgnImportConnectorCallback interface.

The IWgnImportConnectorDeferredCompletion interface will only be supplied if CA DataMinder is intending to save an event in its database. Settings in policy dictate the conditions for this.

If set to FALSE, the messageId and importSource parameters must be set to their final values, because these will be stored in the CA DataMinder database if the analysis against policy dictates it.

Return Values for ImportObject Method

WGN_S_ACTIVEIMPORT_AWAITING_COMPLETION

The caller has set allowDeferredCompletion parameter to TRUE. CA DataMinder has analyzed the message and is intending to save an event for this message is its database. It is now waiting for the caller to commit this transaction or roll it back via the IWgnImportConnectorDeferredCompletion interface.

In this situation, the caller is able to retrieve the Smart Tags generated by the analysis of the message prior to committing or rolling back the transaction.

Success code

A return value that passes the SUCCEEDED() macro, indicating that the message has been successfully analyzed. The results of this analysis, including Smart Tags, can be obtained via the returned results interface, which must be released by the caller. The IWgnSmartTag interface can be obtained by calling GetInterface() on the results interface. The GetProcessingResult() method of the results object will return the same value as this return code.

Error code

Any return value that fails the SUCCEEDED() macro can be returned, indicating that the message has not been fully processed. If the reason for failure is due to network or other catastrophic failure, it is possible that an event was saved to the CA DataMinder database, but the results will not be accessible.

If an error code is returned from this method, the results output parameter value will be NULL.

The GetStatusString() method can be called to convert the returned error code to a string.