Using the Arbortext Object Model and the Repository API with the PTC Server connection

Content Management > PTC Server connection Setup > Using the Arbortext Object Model and the Repository API with the PTC Server connection

You can customize the PTC Server connection 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 Server connection 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 Server connection 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 Server connection:

• 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 Server connection 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 Server connection 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 Server connection 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 Server connection 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 Server connection 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 Server connection 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 Server connection already registers, your custom callback must invoke the corresponding PTC Server connection callback. Following are the PTC Server connection 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 Server connection 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 Server connection 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 Server connection 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.