Using the Arbortext Object Model and the Repository API with the PTC 伺服器連線
You can customize the PTC 伺服器連線 using the Arbortext Object Model (AOM). The AOM includes CMS specific events, that enable you to customize content management system operations. These events often enable you to extend operations as well through pre- and post-operation events. Refer to the Programmer's Reference for more information about the AOM interfaces. See the Event Types topic in that reference for more information about CMS events.
In addition to the AOM, you can also customize the PTC 伺服器連線 using the Arbortext Command Language (ACL) Repository API. Refer to the Arbortext Command Language Reference for more information about the Repository API.
Unsupported AOM Interface Methods
The PTC 伺服器連線 does not support the following methods in the AOM interfaces:
• createFolder method in the CMSSession interface for Arbortext Content Manager and Windchill releases prior to 10.0 F000.
• deleteObject method in the CMSObject interface
Modified AOM Interfaces
Following are the ways the AOM CMSSession and CMSObject interfaces have been modified to work with the PTC 伺服器連線:
• The implementation of CMSSession.GetFile has added support for retrieval of a graphic's secondary content.
If you provide a notation parameter containing the graphic file format when invoking the method, the PTC 伺服器連線 will first search for the specific format in the graphic's primary content. If the specified format is not found in the primary content, the secondary content will be searched. If the file format is not found there or the notation content does not match the graphic type or file extension in either the primary or secondary content, then no content is retrieved and an error is returned.
An exception to this behavior is the case where a Creo View representation file format, such as an EDZ or PVZ file, is specified in the parameter and that file format is available. In this case, the Creo View representation file is always returned.
• You can provide an opcode to the CMSSession.invokeExtension method that enables you to customize the PTC Server numbering rules for a Dynamic Document.
The opcode you provide to the method for this purpose is 2. The PropertyMap you provide must contain an entry with the key WC_NUMBER_ATTR and the value set to the desired number. If you include either %d or %D in the number, then the PTC Server number is included at that place in your custom number. If WC_NUMBER_ATTR is an empty string or just contains spaces, the PTC Server provides the number as usual.
Note that the number you provide cannot contain special characters that are not permitted in a URI. These include, but are not limited to #, ?, \, and spaces.
Following are some example WC_NUMBER_ATTR values:
|
WC_NUMBER_ATTR Value
|
PTC Server Dynamic Document Number
|
|
1223546675
|
1223546675
|
|
%D-Kor-axdocbook
|
serverNumber-Kor-axdocbook
|
|
acme-%d
|
acme-serverNumber
|
You can also provide an opcode of 3 to the invokeExtension method to test whether your custom numbers already exist in the PTC Server. In this case, your PropertyMap’s keys should contain the number(s) that you want to test. The returned PropertyMap contains the numbers found in the PTC Server.
• You can provide an opcode to the CMSSession.invokeExtension method that enables you to delete the workspace specified in the provided PropertyMap.
The opcode you provide to the method for this purpose is 4. The PropertyMap you provide must contain an entry with the key DELETE_WORKSPACE and the value set to the name of the workspace you want to delete. The returned PropertyMap contains an entry with the key result that has one of the following values:
◦ 0 — The operation succeeded.
◦ 1 — The operation failed because the workspace is currently offline.
◦ 2 — The operation failed because the workspace is currently active.
◦ 3 — The operation failed because the workspace does not exist.
◦ 4 — The operation failed for an unknown reason.
• You can provide an opcode to the CMSSession.invokeExtension method that enables you to invoke UWGM Custom Services that are available on the PTC Server. The services can either be default custom services, custom services the PTC 伺服器連線 added to the PTC Server as an extension, or other Windchill APIs that are exposed as UWGM Custom Services.
The opcode you provide to the method for this purpose is 6. You must provide a PropertyMap containing an entry with the key CUSTOM_SERVICE_NAME with the value set to the name of the custom service on the PTC Server you want to invoke. Note that the custom service must be registered on the PTC Server. The property map must also contain any other key and value properties that need to be passed to the custom service.
The returned PropertyMap contains the key and value entries for the invoked custom service. Anyone using a custom service must know the expected key and value formats for the input and returned property maps, such as error codes or returned data formats.
For example, the following property map invokes the Arbortext custom service to return Option and Choice information for a Windchill Service Information Manager Content Holder associated with the dynamic document currently open in Arbortext Editor:
// Set the custom service invocation opcode to "6"
var CUSTOMSERVICE_OP = 6;
// Create the input PropertyMap
var inputMap = Application.createPropertyMap();
// Set the CUSTOM_SERVICE_NAME property to the name of the custom service
inputMap.putString("CUSTOM_SERVICE_NAME","ASPS_OPTION_CHOICE_INFO_SERVICE");
// Set the custom service specific input key/value properties, in this case
// the key is "LOGICALID_OF_DOCUMENT" and the value is the Windchill logical ID
// of the document open in Editor
inputMap.putString("LOGICALID_OF_DOCUMENT","x-wc://file=X000000421.xml");
// Invoke the custom service
var session = Application.getActiveSession();
try {
var resultMap = session.invokeExtension(CUSTOMSERVICE_OP, inputMap);
} catch(err)
{
Application.alert(err);
}
• You can use the CMSSession.search method to programmatically search for content in a PTC Server.
You specify the search criteria using a freeform XML string. The following example is a search (the wcsearch element) for objects that have a name beginning with a c. The overall search constraints are described by wcsearch attributes, with one or more criterion elements selecting objects from within those constraints. The attribute names and values are case sensitive.
<?xml version="1.0" encoding="UTF-8"?>
<wcsearch
CONTEXT="Demo_Search"
CONTEXTTYPE="PRODUCT"
SCOPE="WCTYPE|wt.epm.EPMDocument|com.ptc.ptcnet.i5050.DynamicDocument"
INCLUDESUBTYPE="true"
SHOWVIEWABLEONLY="true"
MATCHALLCRITERIA="true" >
<criteria>
<criterion attrname="NAME" operator="=" value="c*"></criterion>
</criteria>
</wcsearch>
The wcsearch element supports the following attributes:
◦ CONTEXT — Indicates the target PTC Server context's name. The string All Contexts specifies all contexts to which the current user has access.
◦ CONTEXTTYPE — Indicates the context type. The string ALL_CONTEXTS specifies all contexts to which the current user has access. The following values are allowed:
|
Search Context
|
CONTEXTTYPE String for Query
|
|
A particular Product
|
PRODUCT
|
|
A particular Library
|
LIBRARY
|
|
A particular Project
|
PROJECT
|
|
A named Organization
|
ORGANIZATION
|
|
The Site context
|
SITE
|
|
Any context to which a user has access
|
ALL_CONTEXTS
|
|
Any Product context to which a user has access
|
ALL_PRODUCTS
|
|
Any Library context to which a user has access
|
ALL_LIBRARIES
|
|
Any Project context to which a user has access
|
ALL_PROJECTS
|
◦ SCOPE — Indicates the object type. You must specify a fully qualified subtype name in the following format:
wt.epm.EPMDocument|prefix.DynamicDocument|prefix.subtype2| ... |prefix.subtypeN
The prefix is generated by reversing the internet domain for the default organization. Each component must specify the system name of each subtype, not the display name, as given in the PTC Server Type Manager interface. Consult your Arbortext Content Manager or Windchill documentation for more information about object types.
Following is an example:
WCTYPE|wt.epm.EPMDocument|com.acme.DynamicDocument|com.acme.Chapter
◦ INCLUDESUBTYPE — Indicates whether the search should include subtypes of the type specified by the SCOPE attribute. Legal values are true or false.
◦ SHOWVIEWABLEONLY — Indicates whether the results should be limited to objects to which the user has read permission. Legal values are true or false.
◦ MATCHALLCRITERIA — Indicates whether all criterion elements must be satisfied. Legal values are true or false. true represents logically AND'ing the criteria together. false is a logical OR.
The
criteria element groups potentially multiple
criterion elements. Each
criterion is specified by the attributes
attrname,
operator, and
value. The legal operator values are
= and
!=. Refer to the
PTC 伺服器連線 help topic
Search dialog box for details on the wildcards allowed in the
value attribute. The legal attribute names for the
attrname attribute are described in
Assigning PTC Server properties.
For system attributes that are date based (such as Created On), the following values are supported:
|
Search by Date Criteria
|
Criteria Name in Search Query
|
Criteria Value in Search Query
|
|
Documents created or modified any time, equivalent to not specifying a date range
|
WTA_ANYTIME
|
Same as the name
|
|
Documents created or modified between two specified time stamps
|
WTA_BETWEEN
|
“start date - end date”, for example, "1/05/2010 - 2/05/2010" to search for documents created between January 5, 2010 and February 5, 2010
|
|
Documents created or modified today
|
WTA_TODAY
|
Same as the name
|
|
Documents created or modified since yesterday
|
WTA_SINCE_YDAY
|
Same as the name
|
|
Documents created or modified in the last 7 days
|
WTA_LAST_7DAYS
|
Same as the name
|
|
Documents created or modified in the last 30 days
|
WTA_LAST_30DAYS
|
Same as the name
|
|
Documents created or modified in the last 60 days
|
WTA_LAST_60DAYS
|
Same as the name
|
|
Documents created or modified in the last 90 days
|
WTA_LAST_90DAYS
|
Same as the name
|
|
Documents created or modified in the last 180 days
|
WTA_LAST_180DAYS
|
Same as the name
|
• The implementation of CMSObject.checkout has been modified for the case where dependent objects are checked out in the same operation.
Prior to the Arbortext 6.0 release, the entire check out operation would be canceled if any dependent objects were not eligible for check out. For example, if the object was checked out to a different workspace. For the 6.0 and later releases, the check out operation proceeds for all dependent objects eligible for check out whenever possible.
If there are dependant objects that cannot be checked out, that is reported in either the message window or the PTC 伺服器連線 log. However, the report does not list the objects that cannot be checked out or the reason the checkout failed. The entire check out is still canceled when the user cannot access one or more of the dependent objects. For example, if a dependent object has been moved to a product for which the user lacks access permissions.
Using ACL Repository API Callbacks
The PTC 伺服器連線 registers the following Repository API callbacks:
• lock
• unlock
• precheckin
• preburst
• postburst
• autosave
Arbortext Editor maintains a single instance of each callback. When you register a custom callback for one of these operations, this causes a conflict because only one of the callbacks is executed. The PTC 伺服器連線 callbacks contain required functionality and must be executed. If you need to develop your own callback for one of these operations, you have two options.
If you are developing an ACL callback for one of the callbacks the PTC 伺服器連線 already registers, your custom callback must invoke the corresponding PTC 伺服器連線 callback. Following are the PTC 伺服器連線 callback functions:
• lock is implemented as wccmds::checkout_callback
• unlock is implemented as wccmds::undo_checkout_callback
• precheckin is implemented as wccmds::precheckin_callback
• preburst is implemented as wccmds::preburst_callback
• postburst is implemented as wccmds::postburst_callback
• autosave is implemented as windchilladapter::autosave
For example, if you are writing an unlock callback, your callback must invoke the PTC 伺服器連線 functionality by calling wccmds::undo_checkout_callback. These callbacks take the arguments outlined in the Repository API Callback Functions topic in the Arbortext Command Language Reference. This option enables you to invoke the PTC 伺服器連線 callback either before or after your custom code runs.
|
|
You cannot do operations in the preburst_callback that will modify the adapter cache, such as doing a search. The preburst is called during a Save operation in Windchilland modifying the cache may cause corruption.
|
If you are using AOM, you can develop an AOM CMS event handler associated with the operation. Arbortext Editor always triggers an AOM event before the equivalent ACL callback. Following are the CMS event types that correspond to the PTC 伺服器連線 repository callbacks:
• lock corresponds to CMSObjectCheckout
• unlock corresponds to CMSObjectCancelCheckout
• precheckin corresponds to CMSObjectPreCheckin
• preburst corresponds to CMSSessionBurstDocument
• postburst corresponds to CMSSessionPostBurstDocument
Note that there is no AOM equivalent to the autosave callback. Samples of AOM CMS event handlers are in the installation at Arbortext-path\adapters\com.ptc.prowt.arbortext\samples.
