Methods (ISPAdapter) - Integration - Update 46 - Help - Hexagon

SmartPlant Integration .NET Help

Language
English
Product
Integration
Search by Category
Help
SmartPlant Foundation / SDx Version
10
Smart P&ID Version
9 (2019)
Smart Engineering Manager Version
10 (2019)

DocumentExistsInTool

Description

This method checks whether the specified document exists in the tool database or not. This method is used during a re-publish of a document. It is possible that the document was deleted in the tool since the last publish. When you select a document in the ISPCLCommonUI for re-publish, ISPCLServiceManager will make a simple check for document existence by calling this method.

Name

Data type

Input/output

Description

oDocumentIObj

IObject

Input

IObject interface on the document object.

True - If the document exists in the tool

False - If the document does not exist in the tool

Return Value

Boolean

Comments

If the method fails, the tool will raise an appropriate exception.

FindDocsToPublish

Description

This method returns the documents that need to be published. Some design tools keep the required information (last published date, last modified date) in their database to determine if a document needs to be published. Design tools implement this method to compare the last published date and the last modified date, and to add the document to the container passed if the last modified date is later than the last published date. If any documents have been created have not been published, they must be added to the second container passed to this method.

This method is called for only those tools that support this functionality. That determination is made by calling the SupportsFeature method with the FindToPublish argument as described in SupportsFeature later in this section.

For Integration with SmartPlant Foundation, the default hierarchy for documents in the tree on the SPCLCommonUI dialog box is Category > Type > Document. For Integration with SDx, the default hierarchy is DocumentClass > DocumentType1 > DocumentType2. To display documents in a custom hierarchy, add objects and relationships to the oDocsToPublishIContainer and the oNewDocsToPublishIContainer:

For each custom folder, create an instance of PublishDocumentFolder. Property IObject.Name is displayed next to the folder’s icon in the Publish dialog box tree.

To display a folder using a custom icon, get the IPublishDocumentFolder interface of the folder object and populate the PublishDocumentFolder_NormalIconPath property with the full path to the icon that is used when the folder is not selected and the PublishDocumentFolder_SelectedIconPath property with the full path to the icon that is used when the folder is selected. Both properties can use the same icon.

To make one folder be the parent of another, create a DocumentFolderCollection relationship where the child is end 1 and the parent is end 2.

To make a document appear in a folder, create a DocumentsInFolders relationship where the document object is end 1 and the folder object is end 2.

SHARED Tip At this time, custom folders apply only to Integration with SmartPlant Foundation.

ISPAdapter-Method

Arguments

Name

Data type

Input/output

Description

oDocsToPublishIContainer

IContainer

Input

IContainer pointer to documents container. Documents to be published should be added to this container.

oNewDocsToPublishIContainer

IContainer

Input

IContainer pointer to documents container. New documents (not published previously) should be added to this container.

Return Value

None

Comments

If the method fails, the tool will raise an appropriate exception.

GetCompSchemaUID As String

Description

This method returns a corresponding SmartPlant Component Schema UID for a given document type. For a given publishable/retrievable document type, the tool should know what Component Schema the tool will publish for a document type. Purpose of this schema UID is for ISPCLServiceManager to load the Component Schema in memory for the tool adapter to use during publish.

Arguments

Name

Data Type

Input/Output

Description

sDocTypeUID

String (maximum 128 characters)

Input

UID of document type for which the Component Schema UID is requested.

Return Value

Component Schema UID as string.

Comments

If the method fails, the tool will raise an appropriate exception.

GetDocClassDefUID As String

Description

This method returns corresponding SmartPlant schema class definition UID of document for a given document type. This method is used during publish and retrieve. ISPCLServiceManager will create a document object for the adapter to populate with data objects. Before it can create document object, ISPCLServiceManager needs to know the class definition for the document object. ISPCLServiceManager will call this method to get the class definition UID.

Tools will implement this method to return the class definition UID of document object given a document type.

Arguments

Name

Data type

Input/output

Description

sDocTypeUID

String (maximum 128 characters)

Input

UID of document type for which the document class definition UID is requested.

Return Value

UID of class definition of document as string.

Comments

If the method fails, the tool will raise an appropriate exception.

GetDocumentList

Description

This method returns a collection of documents of a given document type in the tool database for a plant. If a null value is passed for document type UID, then the tool should return all the documents of all types it supports in a plant. There are no arguments for plant in this method because these are cached as properties on ISPAdapter interface. Tools should look at these properties.

This method will be used in non-invasive compare operations.

Arguments

Name

Data type

Input/output

Description

sDocTypeUID

String (maximum 256 characters)

Input

UID of document. If the value is NULL, then all publishable document types are returned.

oDocIContainer

IContainer

Input

IContainer pointer to documents container.

Return Value

None.

Comments

If the method fails, the tool will raise an appropriate exception.

GetMapSchemaFile As String

Description

Returns the mapping schema file name, including the full path. This method will be called for tools that support mapping schema. The returned map schema will be loaded by ISPCLServiceManager for tools to use in subsequent publish and retrieve calls.

Arguments

Name

Data type

Input/output

Description

sDocTypeUID

String (maximum 128 characters)

Input

UID of document type for which the Map schema file is requested.

If this parameter is empty and the tool adapter has multiple map schema files for its different supported document types, GetMapSchemaFile should raise an exception. If this parameter is empty and the tool adapter has one map schema files for all its supported document types, GetMapSchemaFile should not raise an exception.

Return Value

Full path to mapping schema file as string.

Comments

If the method fails, the tool will raise an appropriate exception.

GetObjectStatusInTool As ObjectStatusInTool

Description

This method checks the status of an object in the design tool. This call is made to the design tool when an object is found missing in the published data, but was published or claimed previously. Such an object is either deleted, moved, or unclaimed. The return value should be one of the first three of the following enumerations:

enum (

Deleted = 1,

Moved = 2,

Unclaimed = 3,

UIDUpdated = 4

} ObjectStatusInTool

If the return value is Deleted, a tombstone will be generated. If the return value is Moved, the object will be added to a moved object collection. If the return value is Unclaimed, an unclaim instruction is generated and the object will be added to the unclaimed object collection in SmartPlant Foundation.

The new UIDUpdated status was added to object starting with version 3.7. Tools that can return UIDUpdated status for an object should implement ISPAdapter3 interface. The ISPAdapter3 interface also has the GetObjectStatusInTool method. For details, see ISPAdapter3 Interface Class.

Arguments

Name

Data type

Input/output

Description

sObjUID

String (maximum 128 characters)

Input

UID of the object.

sClassUID

String (maximum 128 characters)

Input

UID of the class definition of the object.

Return Value

ObjectStatusInTool.

Comments

If the method fails, the tool will raise an appropriate exception.

GetPublishableDocTypes As ISPDocTypes

Description

This method should return document types that a tool can publish as ISPDocTypes collection object. Tools will implement this method to obtain the list of publishable document types by the tool, add them to ISPDocTypes collection object, and return the collection object.

Arguments

None

Return Value

Publishable document types as ISPDocTypes. If the method fails, the return value is Nothing.

Comments

If the method fails, the tool will raise an appropriate exception.

GetRetrievableDocTypes As ISPDocTypes

Description

This method should return document types that the tool can retrieve as ISPDocTypes collection object. Tools will implement this method to obtain the list of retrievable document types by the tool, add them to ISPDocTypes collection object, and return the collection object.

Retrievable document types should also include PBS document. A PBS document describes the Plant Breakdown Structure of a plant.

In a SmartPlant Foundation plant, there will be one PBS document.

Except Intergraph Smart® 3D, all tools will return PBS document type as retrievable document types along with other document types that they support in retrieve.

For more information on PBS document type, see the Schema Editor Guide.

Arguments

None

Return Value

Retrievable document types as ISPDocTypes. If the method fails, the return value is Nothing.

Comments

If the method fails, the tool will raise an appropriate exception.

GetRevision As String

Description

The purpose of this method is to get the current revision of a document in the tool. SmartPlant Client only calls this method if the publishing tool’s implementation of SupportFeature returns True for ToolRevisions. This method should return a revision value for the document identified by the input parameter.

Arguments

Name

Data type

Input/output

Description

oDocumentIObj

IObject

Input

IObject interface on the document object.

Return Value

Revision as string.

Comments

If the method fails, the tool will raise an exception.

PublishConfirm

Description

This method will be called after a document is published successfully. A tool will implement this method to store the publish date in its database. This is a way to keep track of when a document is published last. The argument for this method is the document IObject interface that identifies the document for which this method is being called.

Arguments

Name

Data type

Input/output

Description

oDocumentIObj

IObject

Input

IObject interface on the document object.

Return Value

None.

Comments

If the method fails, the tool will raise an appropriate exception.

PublishDocument

Description

When a user selects one or more documents to publish, ISPCLServicesManager will call the PublishDocument method for each document. ISPCLServicesManager will get the IObject, IDocument, IissueRecordComposition, and IDocVersionComposition interfaces and will populate the properties on the IObject and IDocument interfaces before calling this method.

The implementation of this method will do the following

  1. Collect all data associated with the specified document.

  2. Use the schema component to create objects and relationships.

  3. Add created objects and relationships to the document data container (passed as an input argument).

  4. Check the value of bViewFileRequired. If it is TRUE, add the graphic file interfaces to the document metadata container (passed as an input argument). A File object should be created for each view file and reference file for the publishing document. The adapter needs to create the necessary view file interfaces and relationships in the metadata container and set the FilePath property.

Arguments

Name

Data type

Input/output

Description

oDocumentIObj

IObject

Input

IObject interface on the document object.

oDocContIContainer

IContainer

Input

Document container.

oDocMetadataIContainer

IContainer

Input

Document metadata container.

bViewFileRequired

Boolean

Input

Indicates whether view files and the reference files need to be added to the metadata container. TRUE will be passed for normal publish operation. FALSE will be passed in cases where view files and reference files are not required. The case for FALSE would be when only the XML is required.

Arguments (Overloaded)

Name

Data type

Input/output

Description

oDocumentIObj

IObject

Input

IObject interface on the document object.

oDocContIContainer

IContainer

Input

Document container.

oDocMetadataIContainer

IContainer

Input

Document metadata container.

bViewFileRequired

Boolean

Input

Indicates whether view files and the reference files need to be added to the metadata container. TRUE will be passed for normal publish operation. FALSE will be passed in cases where view files and reference files are not required. The case for FALSE would be when only the XML is required.

oMapSchContIContainer

IContainer

Input

Map schema container. This argument will be passed for only the tools that support mapping schema.

Return Value

None.

Comments

If the method fails, the tool will raise an appropriate exception.

RetrieveDocument

Description

When a user selects one or more documents to retrieve, for each document, ISPCLServiceMgr will call ISPCLClientApplication to get XML files depending on document type. Then it will call RetrieveDocument for the tool to import the loaded containers (document data, Metadata, tombstones).

Tools will implement this method to loop through the data objects and import them into the design tool database. (For SPPID, this means to generate tasks in the ToDo list.)

The data container has data objects. The metadata container has File objects. There is one File object for each view file associated with the document. The File object has an interface called IFile, which has a property called FilePath, which points to the absolute path of the file. Tools should copy the file from this path to their local path. Adding of File objects happens only if the tool supports retrieval of view files. A tool will communicate whether it can retrieve view files or not by returning TRUE when the SupportsFeature method is called with RetrieveViewFile as an argument.

The tombstones container has four types of instructions for tombstoned objects/relationships, unclaimed objects/relationships (projects only), tombstoned properties, and UID updated objects/relationships.

DeleteInstruction (tombstoned objects and relationships)

Example of DeleteInstruction for an object:

<DeleteInstruction>

<IObject UID="{C69AF85D-DBF8-4C48-A542-E299336A510B}"

Name="Delete_EBB7F9A60CF54168A5E4A00B76C2AD0B" />

<IRefObject RefClass="PIDInstrument"

RefUID="EBB7F9A60CF54168A5E4A00B76C2AD0B" RefName="" />

<IDeleteInstruction />

<IInstruction />

</DeleteInstruction>

Example of DeleteInstruction for a relationship:

<DeleteInstruction>

<IObject UID="{8BCA6E40-B2C1-41A4-B283-17FEE4F4DD94}"

Name="Delete_PBS-EBB7F9A60CF54168A5E4A00B76C2AD0B-N3- FLZBZBMYHIXW-TP2EUSDY" />

<IRefObject RefClass="Rel"

RefUID="PBS-EBB7F9A60CF54168A5E4A00B76C2AD0B-N3-FLZBZBMYHIXW-TP2EUSDY" RefName="" />

<IRefRel RefDefUID="PBSItemCollection"

RefUID1="EBB7F9A60CF54168A5E4A00B76C2AD0B"

RefUID2="N3-FLZBZBMYHIXW-TP2EUSDY" />

<IDeleteInstruction />

<IInstruction />

</DeleteInstruction>

UpdateInstruction (tombstoned properties)

UpdateInstruction is used for tombstoned properties. Tombstoned properties are properties that were previously published but do not exist in the current publish.

If an object has any tombstoned properties, then an UpdateInstruction instance will be created for that object and will identify all of the properties for that object that have been tombstoned. The PropValues property on the IPropValues interface will identify the interface definition and property definition (delimited by \%) for each of the tombstoned properties.

Example of UpdateInstruction:

<UpdateInstruction>

<IObject UID="{29BECC40-202E-4259-88C4-75CFE62CCC9F}"

Name="Update_EQDExchangerAirSide"/>

<IRefObject RefClass="ClassDef" RefUID="EQDExchangerAirSide"

RefName="EQDExchangerAirSide"/>

<IPropValues PropValues="ISchemaObj\%DisplayName\%"/>

<IUpdateInstruction/>

<IInstruction/>

</UpdateInstruction>

UpdateUIDInstruction

If the identity of an object has changed in the publishing tool, an UpdateUIDInstruction is generated with old and new UIDs of the object.

Arguments

Name

Data type

Input/output

Description

oDocumentIObj

IObject

Input

IObject interface on the document object.

oDocContIContainer

IContainer

Input

Document container.

oDocTombstonesIContainer

IContainer

Input

Tombstones container with tombstoned objects, unclaimed objects (projects only), UpdateUIDInstructions, and UpdateInstructions

oDocMetadataIContainer

IContainer

Input

Metadata container

Arguments (Overloaded)

Name

Data type

Input/output

Description

oDocumentIObj

IObject

Input

IObject interface on the document object.

oDocContIContainer

IContainer

Input

Document container.

oDocTombstonesIContainer

IContainer

Input

Tombstones container with tombstoned objects, unclaimed objects (projects only), UpdateUIDInstructions, and UpdateInstructions

oDocMetadataIContainer

IContainer

Input

Metadata container

oMapSchContIContainer

IContainer

Input

Map schema container. This argument will be passed for only the tools that support mapping schema.

Return Value

None.

Comments

If the method fails, the tool will raise an appropriate exception.

RetrieveConfirm

Description

This method is called by the ISPCLCommonUI after a successful retrieval of a document by the tool in the context of a plant. This method has two arguments: one for the retrieved document object and the second for the retrieval time in GMT.

Tools have a choice of storing or not storing the retrieved document UID, but they must store the retrieval time in GMT. If a tool chooses not to store the document UID, then it cannot reset the design basis per document. In other words, the reset design basis methods will be called by the tool with no document ID, and the same reset time is applied to all retrieved documents. If the tool prefers to reset the design basis per retrieved document, then they must store the document UID along with last retrieved time in GMT and pass the retrieved document UIDs in the reset design basis methods.

Arguments

Name

Data type

Input/output

Description

oDocIObj

IObject

Input

Retrieved document object.

dtRetrieveTimeInGMT

Date

Input

The time of document retrieval in GMT.

Return Value

None.

Comments

If the method fails, the tool will raise an appropriate exception.

SupportsFeature

Description

ISPCLCommonUI calls this method when it needs to check with a tool if a feature is supported or not. There are two arguments in this method. The first argument for this method is of type ToolFeatures. ToolFeatures is an enumeration defined in SmartPlantInterfaces.dll as defined below.

Public Enum ToolFeatures As Integer

ToolRevisions = 1,

Mapping = 2,

FindToPublish = 3,

BatchPublish = 4,

BatchRetrieve = 5,

RetrieveViewFile = 6,

NoConfigurationManagement = 7,

NoCorrelationInTool = 8,

SPFRevisions = 9,

ToolBatchPublish = 10,

MultiToolPlantsToOnePlant = 11,

NoMinorRevisions = 12

End Enum

  • The ToolRevisions entry is used to check if the tool supports revisions. When the SupportsFeature method is called with this entry, the tool adapter should return TRUE if the tool supports revisions.

  • The Mapping entry is used to check if the tool uses the mapping schema in publish operations. When the SupportsFeature method is called with this entry, the tool adapter should return TRUE if the tool supports mapping schema.

  • The FindToPublish entry is used to check if the tool supports Documents to Publish functionality. A tool can support this functionality by keeping a record of what documents have been published by saving the last publish date and when the documents have been modified last.

  • If a tool supports this functionality, then when user clicks, ISPCLServiceManager will call the FindDocsToPublish method on the tool adapter to get a list of documents to publish. If the tool does not support the functionality, ISPCLServiceManager will execute its logic to get the list.

  • The BatchPublish entry is used to check if the tool supports publish operations in batch mode.

  • The BatchRetrieve entry is used to check if the tool supports retrieve operation in batch mode.

  • The RetrieveViewFile entry is used to check if the tool supports retrieving (or needs to retrieve) the view file as part of retrieve operation. There is a second optional argument in the SupportsFeature method, called sDocTypeUID. This argument is used with the RetrieveViewFile enumeration entry to let the adapter know the document type for which the check is being done. During a retrieve operation, ISPCLServiceManager makes the SupportsFeature call to the adapter to check if it needs the view file of the document in the retrieve operation. If the answer is TRUE, ISPCLServiceManager will fetch the view files from SPF and make them available to the tool on the client.

  • The NoConfigurationManagement entry is used to determine if the tool supports plant configuration similar to SmartPlant Foundation plant configuration. If the tool does not support plant configuration, then the ISPCLCommonUI will allow registration to a plant depending on where the tool documents will be published and from where the documents will be retrieved. Currently all tools support plant configuration and hence return FALSE for this entry.

  • The NoCorrelationInTool entry is used to determine if the object correlation needs to be done in SmartPlant Foundation or not. The object correlation is a way to say that a published object is same as the object published by other tool. Most of the tools have the ability to correlate objects with other tools’ objects in their environment. Some tools such as PDS do not have correlation capability, as they do not retrieve documents. Thus, the PDS Adapter will return TRUE for this entry, which tells SmartPlant Foundation to generate correlations between PDS objects and other tool objects using name as the matching criteria.

  • The SPFRevisions entry is used to check whether the tool supports the Revise command and uses the SmartPlant Foundation revisioning scheme. A tool that depends on SmartPlant Foundation for revisioning would have to implement the ISPAdapter2 interface and will have to call the revise methods described later.

  • The ToolBatchPublish entry is added for SP3D drawings publish. This entry is used to check whether a tool can support batch publish where the ISPCLCommonUI would return the document selections made in the Publish dialog back to the tool adapter for later publish using ISPCLCommonUIApplicationNoUI interface. The Publish dialog will show an option for tool batch publish. When this option is selected, the ISPCLCommonUI will send the user selections to the tool adapter using ISPAdapter4 interface instead of continuing with normal publish process. The tool will save the user selections for later publish using ISPClientApplicationNoUI interface. A tool that supports batch publish will have to implement ISPAdapter4 interface.

  • The MultiToolPlantsToOnePlant entry is used to check if the tool supports integrating two or more tool plants with one SmartPlant Foundation plant. The tool adapter will set this entry to TRUE so that the ISPCLCommonUIApplicationUI’s dialog will allow registering more than one tool plant with one SmartPlant Foundation plant. Tools should make this entry TRUE only when it is capable of publishing and retrieving documents from multiple tool plants to a single SmartPlant Foundation plant.

  • The NoMinorRevisions entry is used to determine if the tool supports minor revisions. If the answer is TRUE, then the tool does not support minor revisions.

Example Code in Tool Implementation

Public Function SupportsFeature(

ByVal eToolFeature As ToolFeatures,

ByVal sDocTypeUID As String) As Boolean

Implements ISPAdapter.SupportsFeature

Select Case eToolFeature

Case ToolFeatures.BatchPublish

Return True

Case ToolFeatures.BatchRetrieve

Return False

End Select

End Function

Arguments

Name

Data type

Input/output

Description

eToolFeature

ToolFeatures

Input

Feature for which the support is checked.

Arguments (Overloaded)

Name

Data type

Input/output

Description

eToolFeature

ToolFeatures

Input

Feature for which the support is checked.

sDocTypeUID

String

Input

UID of Document type. Used only when this method is called with a value of RetrieveViewFile in the Feature argument.

Return Value

TRUE - If the tool supports the feature.

FALSE - If the tool does not support the feature.

Terminate

Description

This method has been added as per the P&ID team’s request. P&ID will implement this method to release all the resources it obtained during the lifetime of this object. Other tools can take advantage of this method if they have similar requirement. Otherwise, tools will implement this method to do nothing, meaning to add the method with no code.

ISPCLServiceManager will call this method before setting the adapter object to Nothing.

Arguments

None.

Return Value

None.