6 Replies Latest reply on May 19, 2017 9:32 AM by sberic

    addPropertyToProjectMetadataSchema always returns true

    Martin Baker Level 1

      The docs say:

      Returns 1 if Premiere Pro created the new property. Returns 0 if that property already existed.

       

      But I'm always seeing this return true even if the property exists in the project. Bug?

        • 2. Re: addPropertyToProjectMetadataSchema always returns true
          sberic Level 2

          If this is a documentation bug, then many of the APIs suffer from such problems. I reported a similar issue on GitHub here.

           

          The Project.importFiles() API appears to also always return true, even though the documentation suggests that it should return a number based on success or failure of the operation. This certainly feels like a bug, as how else are we supposed to react to failure conditions if everything simply appears to succeed by default?

          • 3. Re: addPropertyToProjectMetadataSchema always returns true
            Bruce Bullis Adobe Employee

            Confusing documentation removed.

             

            Yes, it returns true; in the importFiles implementation, it's testing for whether an error was returned from internal calls; 'true' is the result of confirming that no errors were received, that were not passed on to the user. The import error was already passed on to the user, in the form of an import error dialog.

             

            How to react to failure conditions = a common practice (by those who manage the metadata of imported items) is to count the items in the destination bin before and after the import, then operate on the newly-added items.

            • 4. Re: addPropertyToProjectMetadataSchema always returns true
              sberic Level 2

              Bruce Bullis wrote

               

              Confusing documentation removed.

               

              Yes, it returns true; in the importFiles implementation, it's testing for whether an error was returned from internal calls; 'true' is the result of confirming that no errors were received, that were not passed on to the user. The import error was already passed on to the user, in the form of an import error dialog.

              Understood. Did this explanation make it into the updated documentation?

               

              Bruce Bullis wrote

               

              How to react to failure conditions = a common practice (by those who manage the metadata of imported items) is to count the items in the destination bin before and after the import, then operate on the newly-added items.

              Holy crap. I especially hope that this made it into the documentation... Obvious-though-it-may-seem once you've thought about it, APIs such as this tend to return a boolean describing whether the operation succeeded or failed, not whether some deeper internal issue occurred (at which point one would expect it to also return false).

               

              Look at it this way: what are we, the consumers of your API, supposed to do with information that says "Hey, something went wrong internally"? We don't have access to the internals and the value is not an enum describing what kinds of things might have gone wrong for us to report or work around. What we care about as consumers of the API is whether it succeeded or failed.

               

              The confusion here is that it returns a boolean, but not one that we would expect. I recommend explicitly documenting the above process for checking for success or failure of the API and suggest that the documentation also point out that, if that process is followed, the return value should be ignored.

              • 5. Re: addPropertyToProjectMetadataSchema always returns true
                Bruce Bullis Adobe Employee

                I agree with your assessment of API's tendencies to return success or failure; still, we won't be changing the return value from importFiles(), at this point. Also, yes, adding that 'common practice' info would be helpful.

                 

                Regarding your "What are consumers of the API supposed to do" question...I'm not sure where you were presented with info that says 'Hey, something went wrong internally". With importFiles, it would seem that you'd have the obverse problem; "Something may or may not have worked, but you're not telling me".  I suppose the broad answer is "Ask us", as we're pretty responsive.

                 

                Yes, there are problems and shortcomings with the documentation, and sample code. Both are still works in progress. There are literally hundreds of PPro panels in use, today, that were created with zero docs, and rougher sample code. While getting started could certainly be easier, I don't think current docs/code are a barrier to entry; we're happy to help.

                • 6. Re: addPropertyToProjectMetadataSchema always returns true
                  sberic Level 2

                  Bruce Bullis wrote

                   

                  Regarding your "What are consumers of the API supposed to do" question...I'm not sure where you were presented with info that says 'Hey, something went wrong internally".

                  You just presented it to me in this thread:

                   

                  ... in the importFiles implementation, it's testing for whether an error was returned from internal calls; 'true' is the result of confirming that no errors were received, that were not passed on to the user.

                   

                  So, if importFiles() returns false, something went wrong internally and Premiere couldn't (or didn't) inform the user. It would honestly be more useful to have such an API return one of the following:

                  • A Array<ProjectItem> object containing references to the successfully imported items. Then you could easily cross-check what was properly imported and what wasn't based on the return value.
                  • An enum value (integer, constant, etc.) with information about what happened. Something like: 0 = Success, 1 = Failure (User Notified), 2 = Failure (User Not Notified), etc.

                   

                  I do understand that this will not change soon. I'm mentioning it here so that you can point to a customer request in the future when further such APIs are added and there's an internal argument about how to structure the calls.

                   

                  Bruce Bullis wrote

                   

                  With importFiles, it would seem that you'd have the obverse problem; "Something may or may not have worked, but you're not telling me".  I suppose the broad answer is "Ask us", as we're pretty responsive.

                  I'm not sure what you mean about having the obverse problem with this: "Something may or may not have worked, but you're not telling me." Here's how I would expect this to work given the boolean result:

                   

                  if (!app.project.importFiles(["file1.mov", "file2.wav"]))
                  {
                       // One or more of the files did not successfully import.
                       //  Depending on my situation, I may check to see which
                       //  one and notify the user or attempt to modify a file
                       //  in some way and then re-attempt the importation.
                  }
                  /*else
                  {
                       // If importFiles returns true, then there was no error
                       //  and all files were properly imported.
                  }*/
                  

                   

                  By simply looking at the API's footprint, I would assume that it works as above. More information on why something failed would be excellent, but at least I don't have to jump through extra hoops to figure out if there even was an issue to begin with.

                   

                  Bruce Bullis wrote

                   

                  I suppose the broad answer is "Ask us", as we're pretty responsive.

                   

                  Yes, there are problems and shortcomings with the documentation, and sample code. Both are still works in progress. There are literally hundreds of PPro panels in use, today, that were created with zero docs, and rougher sample code. While getting started could certainly be easier, I don't think current docs/code are a barrier to entry; we're happy to help.

                  Yes, I understand that we are encouraged to ask about APIs and pour over sample code to figure stuff out. Technically that's what I'm (we're) doing right now! In this case, the documentation that does exist (and for which we are extremely grateful) simply has some issues that could use some clarification.

                   

                  I understand that you guys are working on it and I seriously appreciate that. I was surprised at how quickly you jumped on the GitHub ticket I opened about the documentation issue and pushed some adjustments! Awesome.

                   

                  What I was trying to point out to you in those last paragraphs is that what you consider "common practice" is not obvious for users unfamiliar and inexperienced with the Premiere Pro APIs. When using the APIs for the first time, one might write some script that looks exactly like what I wrote above. However, the contents of the if-block will rarely-if-ever be processed and a bug will ensue. It may even be one that takes a good deal of time to track down. The purpose for providing this information was to give you a better sense of where I as a "consumer of the API" is coming from such that future documentation efforts may better speak to your user-base.

                   

                  Yes, you guys have literally hundreds of PPro Panels in use. That's fantastic. But the amount of time collectively burned for each developer trudging through the development may be a surprisingly high value. Which is not fantastic. As a user, the knowledge that there are hundreds of other developers who've figured it out before me isn't super useful and feels like more of an admonishment than a help. At the end of the day, we'll get there. It may simply be a slow, painful process.