API commands, also referred to as Server API, are instructions or commands sent by clients to Content Server through DMCL.
API commands can be executed via the following means:
- The IAPI utility
- Web clients such as Documentum Administrator API Tester or Web Publisher
IAPI is short for Interactive API Utility and is available once you install Content Server. On the Content Server host you can find the executable iapi32.exe on Windows machines at the following location:
%DM_HOME%in, e.g. C:Documentumproduct5.2in (for example)
You can invoke the executable directly from the command prompt as shown in figure 26.10 or you can click on the IAPI button shown in Documentum Server Manager window (refer to figure 26.11). In both scenarios, you will need to provide details such as Docbase name and user/password before you start issuing API commands.
26.10: IAPI window
Figure 26.11: IAPI button shown in Documentum Server Manager
API commands can be executed from within Documentum Administrator by clicking on the API button shown in the top right-hand side of the toolbar. This opens the Api Tester screen as shown in figure 26.12.
Figure 26.12: Api Tester utility in Documentum Administrator
Server API commands follow a defined pattern. You need to type the exact method name followed by arguments as a continuous string with comma as a delimiter, separating the various parts. Here is a sample API command:
API> create,c,dm_document
Let us break up this command and explain each term:
create:API method name used to create an object instance of the specified object type.c:Alias for the current session within which the API command is being executed.dm_document:The argument of thecreatemethod. In this case, it is the object type of the object that needs to be created via this API command.
Please keep in mind that the arguments to all the API methods are positional. This means that there are placeholders for all the arguments in an API command even if the argument is optional.
For example, if an API command api_command has four optional arguments first, second, third, and fourth as follows: api_command,c,first,second,third,fourth, then to execute this API command with only one argument, fourth, the command needs to be executed as follows:
API>api_command,c,,,,<value of fourth argument>
Note how placeholder commas have been put for the arguments first, second, and third, even though we are not specifying any values for these arguments.
Depending upon their specific nature and purpose, Server API methods can be grouped together into various categories. The table shown in figure 26.13 shows a few methods and categories based on their nature.
|
Category |
API method |
Use |
|---|---|---|
|
Object management |
|
Attaches an object to a lifecycle. |
|
|
|
Checks out an object from the Docbase and places an explicit lock over it. |
|
|
|
Removes the lock on a checked out object and saves it in the Docbase as a new version. |
|
|
|
Promotes a SysObject from its current normal lifecycle state to the next normal state. |
|
Server communications |
|
Creates a session with the Docbase. |
|
|
|
Disconnects a Docbase session. |
|
|
|
Begins a database transaction. |
|
|
|
Commits changes made during a database transaction and closes the transaction. |
|
Getting and setting attributes |
|
Gets the value of the specified attribute of an object. |
|
|
|
Sets the value of the specified attribute of an object. |
|
System administration |
|
Running an administrative function. |
|
|
|
Allows for auditing of the particular event. |
|
|
|
User name and password validation. |
|
Docbase search |
|
Returns the object ID of the object which satisfies the specified condition |
|
|
|
Runs a DQL query that does not require database access while processing query results. |
|
Content handling |
|
Returns the content file in the specified format. |
|
|
|
Sets a content file to an object. |
|
Lifecycle management |
|
Installs a lifecycle that has been validated. |
|
|
|
Determines whether the lifecycle is valid or not. |
|
|
|
Uninstalls a lifecycle that is currently installed. |
|
Workflow management |
|
Starts the specified workflow. |
|
|
|
Terminates the specified workflow. |
|
|
|
Posts an event to the specified workflow. |
As we did for DQL, let's take the same example of creating a document object, setting its attribute values, linking it to a cabinet in the Docbase, and finally saving it. We will then retrieve this document object from the Docbase and delete it. You will come across a number of API methods while working on this simple example.
Log in to Documentum Administrator as an administrator and open the Api Tester screen.
Refer to figure 26.14; run the create API command by entering the string create,c,dm_document in the Command box as shown in the Api Tester screen and clicking on the Execute button.
Make sure that you do not enter white spaces anywhere in the command string.
"Figure 26.14: Running the API command create using Documentum Administrator
The create API method creates an object of the specified object type (dm_document in our example) and returns the object ID of the newly created object. As shown in the figure 26.14, the object ID of the newly created document object is 090015558000c629.
Note that the newly created object is not committed to the Docbase until you issue an explicit save API command as we will see later in this example.
The set API method can be used to set particular values for single as well as repeating attributes of objects. Set the object_name attribute of the newly created document object as shown in figure 26.15.
Figure 26.15: Setting an attribute value via API command
Note that the method command and arguments are entered in the Command text box while the value of the argument is specified in the Data box as shown in figure 26.15. You must have noticed the peculiar letter l used in the command string: set,c,l,object_name.
This is an alias for the last created, retrieved, checked in/out, or fetched object ID. If you do not want to use the alias l, you can instead run the command as:
set,c,090015558000c629,object_name
Here 090015558000c629 is the object ID of the newly created document object in our example.
The other attributes, such as title, for the document object can be set accordingly as follows:
API>set,c,l,title
Data: File created via API commands
...
OK
You can set the repeating attributes (e.g. keywords) as follows:
API>set,c,l,keywords[0]
Data: document
...
OK
API>set,c,l,keywords[1]
Data: api
...
OK
This sets document and api as the two keywords for the document object at the first and second index positions respectively.
The setfile API method can be used to associate a content file with an object. The prerequisite is that the content file should be present on the machine (client) from where the setfile command is executed. Note that since in our case we are executing the API commands from the Documentum Administrator host as our client, the content file to be set should be locally present on the machine where Documentum Administrator has been installed.
Create a content XML file (say testing_api.xml) and place it at a convenient location on the. Documentum Administrator host, for example: C:Test.
Issue the following setfile command:
API>setfile,c,l,C:Test esting_api.xml,xml
...
OK
Notice the additional argument (xml) specified in the setfile command following the complete path to the content file. This is the name of a valid format for the content file and should be recognized by the Content Server.
Most people place the content file locally on the machine through which they access Documentum Administrator URL via a browser, rather than placing it on the Documentum Administrator machine. Under such scenarios, the following error is thrown by Content Server when you issue the setfile API command:
"[DM_SYSOBJECT_E_CANT_ACCESS_FILE]error: "Cannot access file C:Test esting_api.xml due to Operating System error: The system cannot find the file specified.
"; ERRORCODE: 100; NEXT: null"
Once you have created a document object and set its attributes and content file, the next step is to associate it with either a cabinet or a folder residing within a cabinet. We will use the link API command in our example to associate the newly created document object with a custom cabinet.
As a prerequisite, create a custom cabinet Testing_API_DQL in Web Publisher and then issue the following link command:
API>link,c,l,'/Testing_API_DQL'
...
OK
Tip
You can either link an object with a cabinet or folder using the folder path as we saw in our example, or by referring to the object ID of the cabinet or the folder. For example, if the object ID of Testing_API_DQL cabinet is 0c0015558000c62a, you can link the document object to this cabinet as follows: API>link,c,l,0c0015558000c62a
Until and unless XE "Docbase" "See also objects, Documentum concept" Documentum concept:saving in Docbase" you explicitly issue the save API command, the newly created document object is not saved in the Docbase. Following is an example displaying how to use the save API:
API>save,c,l
...
OK
Once you have saved the document object, you can have a look at it by logging in to Web Publisher and browsing to the Testing_API_DQL cabinet. Figure 26.16 shows how the document object appears in Web Publisher.
Figure 26.16: Newly created document object as seen in Web Publisher
If you select the checkbox against the document object and choose the menu option File | View, you will be able to view the associated content file testing_api.xml.
In order to look at the properties of the document object, you can either click on the Info icon 
or select the checkbox against the document object and choose the menu option View | Properties | Info. Figure 26.17 shows the various properties for the document object that we set using API commands in this example. Note in particular the Name, Title, and Keywords fields shown in figure 26.17 that we set using the API command set.
26.17: Properties of the document object
You can issue the id API command to obtain the object ID of an object that satisfies a particular qualification. Say for example we issue the id API command with a qualification statement "dm_document object whose name is TestDocumentCreated_via_API" as follows:
API>id,c,dm_document where object_name = 'TestDocumentCreated_via_API'
...
090015558000c629
The server returns the object ID 090015558000c629 for the document object TestDocumentCreated_via_API.
Note that you need not enter the complete search qualification starting from select and specifying the from clause. Instead you simply need to enter the clause starting after the from keyword.
Once you have obtained the object ID of the document object, getting the values of its various attributes is very simple. All you need to do is issue a get API command specifying the attribute whose value needs to be found out.
For example, in order to find out the value of the second keywords attribute for the retrieved document object, run the get API command as follows:
API>get,c,l,keywords[1]
...
api
The server returns the value api as the value contained at the second position in the keywords attribute. We have used an index position [1] in this case because keywords is a repeating attribute that stores values starting at index position 0 onwards. In the case of a single-valued attribute, you need not use any square brackets. For example, to find out the value of the title attribute, run the command as follows:
API>get,c,l,title
In order to look at all the attributes and their values for a particular object in the Docbase, use the dump API command. Run the dump API command as follows:
API>dump,c,090015558000c629
…
We have specified the object ID of the document object (090015558000c629) as an argument in the dump API command. Figure 26.18 shows a snapshot listing a dump of the various attributes values of the document object we had created.
Figure 26.18: Snapshot of a document object dump
Note that the server returns the object attributes organized into various categories such as USER ATTRIBUTES, SYSTEM ATTRIBUTES, APPLICATION ATTRIBUTES, and INTERNAL ATTRIBUTES.
You need to issue the destroy API command in order to remove a particular object from the Docbase. Run the following API command in order to delete the document object we created in our example:
API>destroy,c,090015558000c629
…
OK
If the object is checked-out (and thus locked), running the destroy API command throws the following error:
Error processing command:DfException:: THREAD: http8080-Processor8; MSG: [DM_SYSOBJECT_E_CANT_DELETE_LOCKED]error: "Cannot delete sysobject TestDocumentCreated_via_API since its locked by user documentum."; ERRORCODE: 100;
In order to remove the lock on the object either check-in the object by running the API command: checkin,c,090015558000c629 or unlock the. object as follows: unlock,c,090015558000c629.
We have covered several examples in this chapter, demonstrating the power of DQL queries and Server API commands in Documentum. For a complete and exhaustive coverage of DQL and API, it is advisable to go through the Content Server DQL and API reference manuals respectively.