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:
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.
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.
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 the create
method. 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.
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.
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
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.
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.
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.
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.
3.139.81.254