6 Replies Latest reply on Sep 17, 2018 7:26 AM by valentin.stn

    Is there a Interface Specification Document Template?

    valentin.stn

      Hello everyone!

       

      I have a documentation-related question regarding an interface we're building to connect our software to the PI system: Is there any "official" template, some best practices, or at least a good example for such an interace specification document? It is the document we'd like to provide to our customers with the required instructions to set-up and maintain the system.

       

      Thanks all for the responses in advanced!

        • Re: Is there a Interface Specification Document Template?
          gregor

          Hello Valentin,

           

          At OSIsoft we use the term Interface for data adaptors that collect data from data sources like DCS systems or 3rd party databases. PI Interfaces support a certain communication standard like e.g. the PI Interface for OPC DA supports the OPC DA standard. Some Interfaces support not just read but also write operations. While Interfaces write against PI Points, the next generation referred to as PI Connectors work Asset Centric. Please refer to PI Interfaces and PI Connectors.

           

          After visiting your companies homepage, my impression is that you like to create a custom data adapter for your visualization and analysis product which consumes PI Server data. Is this the case? If so, your ask is likely what operations your custom data adaptor should support and I believe the answer is this depends on what information your application needs and e.g. how flexible you like to design it to allow adoption to existing installations. I am afraid you will have to ask more specific and share more details of what you are planning to do to enable us providing you with useful guidance.

          2 of 2 people found this helpful
            • Re: Is there a Interface Specification Document Template?
              valentin.stn

              Dear Gregor,

              First of all, thanks a lot for your helpful answer!
              > After visiting your companies homepage, my impression is that you like to create a custom data adapter for your visualization and analysis product which consumes PI Server data. Is this the case?
              Your impression is correct. We want to use PI server data as source for our visualiaztion and analytics software. Therefore we want to connect through the PI Web API.
              > If so, your ask is likely what operations your custom data adaptor should support and I believe the answer is this depends on what information your application needs and e.g. how flexible you like to design it to allow adoption to existing installations
              For the beginning, we want to focus on more basic operations, like retrieving time series data together with "some" meta data. In the second step, write operations should be added  as well.
              Best regards,
              Valentin
                • Re: Is there a Interface Specification Document Template?
                  gregor

                  Hello Valentin,

                   

                  I see you have identified PI Web API as the Developer Technology to use with your project already. Because it is an important decision which should be taken wisely, I like to offer you to review your decision. If you are interested, please let us know what platform you are developing on, what developer language you prefer, what developer tool(s) you use and if you have some special requirements e.g. built-in security which would be one of the reasons to decide in favor of PI Web API. But if you plan creating a Windows service with C# in Visual Studio and for this service you don't need to support multiple Windows identities, AF SDK may be the better fit.

                   

                  To get started with PI Web API, I suggest you following along the exercises of the Programming in PI Web API online course.

                   

                  You could use our public PI Web API endpoint to exercise with read operations. The advantage is that you don't need to care to install a PI System and PI Web API but could immediately start exercising. As soon as you like add or modify data, you will have to install your own instance to work against.

                   

                  Marcos has created PI Web API 2018 client libraries to support development on many platforms with many languages. These libraries are very useful since they allow you to focus on developing your application in the language of your choice without looking into the details of PI Web API specific implementations. Please note that libraries are offered "as-is" under the Apache 2.0 license which means you could use and enhance them according to your needs but at the same time those libraries are no official products. If you experience trouble using them, please post your issue as question at PI Developers Club and we will try to get them sorted out. Please do not contact OSIsoft Technical Support for issues with these libraries.

                  1 of 1 people found this helpful
                    • Re: Is there a Interface Specification Document Template?
                      valentin.stn

                      Dear Gergor,

                       

                      thanks a lot for your answers. We are quiet sure to have that the Web API is the right technology for us, but please free to review it from your point of view: Our software has a client server architecture, which already heavily involves web technologies, meaning you can think about a team of web developeres. (With a Django/Python server, Angular frontend, etc.). Furthermore, we deploy our software sometimes in quiet complext IT environments with a lot of Firewalls and stuff like that, and anything which does not use normal http web transfers is usually not that easy to establish.

                       

                      Thank you also for the resources, but honestly, my first question was not yet answered. Is there some kind of template regarding the specification of such an interface which customers using OSI systems expect to get?

                       

                      Thanks,
                      Valentin

                        • Re: Is there a Interface Specification Document Template?
                          gregor

                          Gregor wrote:

                           

                           

                          .. your ask is likely what operations your custom data adaptor should support and I believe the answer is this depends on what information your application needs and e.g. how flexible you like to design it to allow adoption to existing installations. I am afraid you will have to ask more specific and share more details of what you are planning to do to enable us providing you with useful guidance.

                           

                          I believe I had answered your question but I recognize that my answer may not have been clear enough. The document you are asking does not exist.

                          The PI System is understood as a data infrastructure. Our customers operate in different industries and even within a certain industry the usage may differ. Different departments may even have different ideas about looking at the data and some customers address this by creating different AF Databases servicing different requirements. On the other hand there exist recommendations e.g. for using Templates when modeling an AF structure and for using Element and Attribute categories.

                          2 of 2 people found this helpful