Error on aaApi_CheckOutDocument (58014, Document is not out)

Mandi,

Can you please post a code snippet of how you are calling the function as well as what version of ProjectWise Explorer, ProjectWise SDK, and the version of the ProjectWise where the datasource is hosted?  A screenshot showing the problem document in PWE might be helpful as well.

I have not personally encountered this particular error.  Judging from the error code 58014 - AAERR_DMS_ERR_ITEM_NOT_OUT, I would suspect that perhaps the file transfer from the storage area to the local working directory failed, but that's just a guess.  I'm not sure what error message you would get if the user does not have write access to the working directory, or if the working directory does not exist.  I assume that the user's' working directory exists, and has write access.

I assume that the user isn't trying to check out a previous version, just the active document.

Does this work for any document, or is this failing for only one, or some subset of documents?

As far as logging to the pw.log file directly, I don't believe that is possible.  What is possible is to turn up the priority to DEBUG in the log configuration file pwc.log.xml for some or all of the categories.  I wouldn't leave the priorities turned up longer than need to capture any helpful debug information.  I would start with setting the categories pwise.dms, pwise.ft, pwise.ft.dft to DEBUG.

If you mean that your application is not a custom module, but a stand alone application, then you might consider capturing any error messages to your own log file.  You can do this with aaApi_SetErrorLogFile() and aaApi_SetWriteErrorLogMode().

Hi Dan,

Thank you very much for the reply.  We are using a proxy to wrap the api in c# but the gist of the check out is like below. The ProjectWiseDocument object is a wrapper and is created using the below FindDocument code.

ProjectWise Versions at Customer: Explorer (10.0.3.167) Server(10.0.3.140 )

ProjectWise Versions in development environment: Explorer (10.00.03.280) Server & SDK (V81 08.11.11590) 

This is failing for all documents. This is a standalone application.  This checkout is used to create a new version of the file.  It has been suggested that we should not do the checkout but rather replace the file directly with a new version.  This mechanism was used so we could checkout with overwrite or check in new version with the same code.  

        public string CheckOutDocument(ProjectWiseDocument doc, String localPath)  //local path can be empty string for default PW working path or a valid path we specify.  Both seem to fail the same
        {
            StringBuilder fileName = new StringBuilder(1024);

            if (!string.IsNullOrEmpty(localPath) && !Directory.Exists(localPath))
                Directory.CreateDirectory(localPath);

            if(!ProjectWiseAPI.aaApi_CheckOutDocument(doc.ProjectID, doc.DocumentID, localPath, fileName, 1024))
            {
                throw new Exception(String.Format("ProjectWiseAPI.aaApi_CheckOutDocument failed for [{0}/{1}]: {2}/{3}", doc.ProjectID, doc.DocumentID, !string.IsNullOrEmpty(localPath) ? localPath : "<null>", fileName.ToString()));
            }           
            return fileName.ToString();
        }
		
		
		public ProjectWiseDocument FindDocument(ProjectWiseProject folder, string fileName, LogFunction log)
        {
            int count = 0;
            ProjectWiseDocument doc = null;

            count = ProjectWiseAPI.aaApi_SelectDocumentsByProjectId(folder.ProjectID);
            for (int i = 0; i < count; i++)
            {
                string docName = ProjectWiseAPI.aaApi_GetDocumentStringProperty((int)DOC_PROP.NAME, i);
                string docFileName = ProjectWiseAPI.aaApi_GetDocumentStringProperty((int)DOC_PROP.FILENAME, i);

                if (docName.ToUpper() == fileName.ToUpper() ||
                    docFileName.ToUpper() == fileName.ToUpper())
                {
                    int id = ProjectWiseAPI.aaApi_GetDocumentNumericProperty((int)DOC_PROP.ID, i);

                    if (id != -1)
                    {
                        doc = new ProjectWiseDocument(this, folder.ProjectID, id);
                        if (doc == null)
                        {
                            if (log != null)
                                log(string.Format("Found the Document but failed to create a new internal document class to return:  {0} ID = {1}", docName, id));
                        }

                        break;
                    }
   
                }
            }
            return doc;
        }

If I understand what you are saying is that the version of the ProjectWise SDK being used is version 08.11.11590, but the clients and server versions are all CONNECT Editions - 10.0.3.*, then I would update your development environment to use a CONNECT Edition SDK.

There's a new developer portal available that makes it easier to find the PW SDKs as well as other SDKs.  Here's a link to the announcement: https://communities.bentley.com/products/programming/microstation_programming/f/microstation-programming---forum/195909/bentley-developer-portal 

Once you go to the portal, you can then select the SDKs pull down, then Project Delivery, and then ProjectWise Design Integration.  You then can use the "Downloads By Type" tool to select whatever makes sense for you.  Taking the defaults, I see 6 available versions.  I would pick whatever version is most likely to be on the client's machine, which doesn't always have a corresponding SDK version.

Based on what you mention above, I would recommend using version 10.00.03.140.

FWIW, It is OK to use C#, but it would be helpful if you also post how you manage the interaction between manage and unmanaged code, as sometimes that can be where the issue actually is.  Also, if you aren't aware, Dave Brumbaugh as made his C# classes available, which can save you a lot of time and effort for much of the PW SDK.  You can get the latest version of MostOfDavesClasses here:  https://github.com/DaveBrumbaugh  In addition to providing a way to call many of the PW SDK functions, he also provides what I would call "helper methods" from many "common use" scenarios.  So before creating a method to do something, see if Dave's already provided a convenient (and tested) method to do what you need.  

I have provided some "sample" code using MostOfDavesClasses here:  https://github.com/DanWilliamsAtBentleyDotCom

I hope to add more samples in the future.  The next one on my list is how to implement ProjectWise hooks in C# which Dave has used.

Please let me know if updating the SDK version that you are using "fixes" the problem, and if not, please post a screenshot of the properties of the document that is failing.

Looking at your code for the FindDocument method, and I haven't checked this for a while, but your "find" could be selecting document versions as well as the active documents.  To be sure that you are only attempting to check out the active documents, you might get and check the document property DOC_PROP_ORIGINALNO and only attempt checking out active documents.

It isn't clear to me what you mean by "versions".  In ProjectWise, you can only create a new version of a document if it is checked in.  If by "version" you mean updating the attached file, then again, you can only replace or add a file to a document if it is checked in.  It sounds like you are replacing the attached file by checking it out, replacing the file that was copied out with an updated "version" of the file, and then checking it back in.  Of course, this type of "versioning" isn't what ProjectWise versioning does.

It sounds like the customer wants to simulate the exact behavior of a drag/drop onto projectwise explorer and a selection of "No Wizard" in the first dialog and "create a new version of an existing document" in the second dialog.  What is the appropriate order of apis to achieve this?  

Upgrading the api is a good recommendation. Thank you.

Mandi, that's quite an open question and the answer depends upon the details of the behavior that you want to achieve, since the "exact behavior" of ProjectWise explore for drag and drop depends upon several user settings, so the "default" behavior can vary from user to user.

Since this is a standalone application of your design, you need to determine how to implement the drag/drop onto your application.  Assuming that you end up with a collection of some sort of the files dropped, and assuming that you "know" or can determine where those files are to be place into the datasource, then you can deal with each file from the collection in a manner that makes sense in your application.

For each file, you can either try to create a document for that file, and catch any errors, and if the error is something "file already exists", then locate the existing document with that file, and create a version of that file.  Or, first look in the target location to see if there already exists a document with a file the same name, and if there isn't one, create a new document, and if there is an existing document using that file name, then create a new version of that document.

And if you have created a new version of an existing document, then you need to replace the attached file with the one from your collection, or, like you have implemented, you can check the document out, overwrite the local file, and then check it in to overwrite the file in the storage area.  Replacing the existing file is faster than checking it out, overwriting it and then checking it back in.

However, there are other rules enforced by ProjectWise when you replace a file on a document, which must be currently checked in.  For one, you cannot replace it with a different file type (or mime type).  To do that, you first need to remove the file from the document, and then add your file to the document.

As for which API functions to use?  There can be multiple ways to accomplish a task, so you will need to do a bit of "research" (reading) the help/documentation, but here are some you might consider:

Since you would know where to place the file, i.e. you know the ProjectWise folder, you can use aaApi_SelectDocumentsByNameProp() to see if there is an existing document that has a file of the same name.  There are other function to search for a document with specific properties of course.

To create a new document, there are again multiple functions, but aaApi_CreateDocument(), aaApi_CreateDocument2(), or aaApi_CreateDocumentsFromFiles() might be of use.

To create a new document version, aaApi_NewDocumentVersion(), aaApi_NewDocumentVersion2(), or aaApi_NewDocumentVersion3() may be of use.

To replace a file on the active document that is checked in, aaApi_ChangeDocumentFile(), aaApi_ChangeDocumentFile2(), aaApi_ChangeDocumentFile3(), or aaApi_ChangeDocumentFile4() may be of use.

To remove a file, try aaApi_DeleteDocumentFile(), and to add your file after you remove the existing file, try aaApi_AddDocumentFile().

aaApi_ChangeDocumentFile4() has a flag parameter that you can set for adding or replacing a file, so you might try that for either action, and just adjust the parameter values accordingly.

And, general advice, watch out for deprecated functions.