ReliaSoft API Reference: Difference between revisions

From ReliaWiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(50 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Template:API}} {{InProgress}}
{{Template:API}}


The  ReliaSoft Synthesis API enables you to programmatically read and write data in Synthesis desktop applications. The API has been developed for Visual Basic for Applications (VBA) and Visual Basic.NET. This gives you the ability to create automated solutions using popular Microsoft Office applications, such as Excel and PowerPoint, as well as create custom applications for your organization.
<div style="border:1px solid #D0CDE8; background:#EEEDF7; border-radius:10px; width:auto; margin:0 0 1em 1em; padding:1em; float:right;">
*'''[[API Changelog|Changelog]]'''
*'''[[API Reference Documentation|API Documentation]]
*'''[[API Tutorials|Tutorials]]
</div>


== Requirements  ==
The ReliaSoft ''Application Programming Interface'' (API) enables you to programmatically read and write data to ReliaSoft repositories, as well as analyze and plot data sets from external sources. It is provided for Visual Basic for Applications (VBA) and .NET applications, allowing you to create automated solutions using popular Microsoft Office applications, such as Excel and PowerPoint, or create custom applications for your organization.
Before using the Synthesis API, note the following requirements:


*You must reference the required Synthesis API library in your .NET project or VBA file ([[Referencing_an_Object_Library|show me how]]). The library is located in the folder where the Synthesis applications are installed. By default, this folder is at C:\Program Files\ReliaSoft\Synthesis 10" (for Version 9, it is "C:\Program Files\ReliaSoft\Synthesis 9").
Implementing the ReliaSoft API allows you to connect data in repositories with the systems and tools used within your organization. It provides the functionality to:


:*For VBA developers, use the SynthesisAPI.tlb library
*'''Transfer and synchronize data via XML'''
:*For .NET developers, use the SynthesisAPI.dll library
:Use XML files to manage structured data (such as system hierarchies/BOMs, incidents and work orders) between ReliaSoft’s [https://www.hbkworld.com/en/products/software/analysis-simulation/reliability/xfracas-failure-reporting-analysis-corrective-action-system-fracas-software XFRACAS] and a variety of different PLMs, ERPs, CMMS and other external systems. You can also use XML files to create reliability block diagrams (RBDs) in [https://www.hbkworld.com/en/products/software/analysis-simulation/reliability/blocksim-system-reliability-availability-maintainability-ram-analysis-software BlockSim].
*'''Read/write specific data elements'''
:Read or write data to resources (models, actions, URDs, etc.), system hierarchy items and FMEA records (causes, effects, failures, etc.). Initiate batch data processing and create custom solutions for importing/exporting data from ReliaSoft repositories, as well as load data into the Reliability Data Warehouse (RDW).  
*'''Obtain calculated results'''
:Read data from published models and obtain calculated results such as reliability, probability of failure, BX% life, failure rate and mean time.
*'''Analyze data'''
:Use [https://hbkworld.com/en/products/software/analysis-simulation/reliability/weibull-life-data-analysis-software Weibull++'s] analysis and plotting engines to analyze data from third-party sources, and incorporate the functionality into your own custom applications. (Requires a ReliaSoft API license.)


*The version of the Synthesis Platform that you've installed (32- vs. 64-bit) must match your installed version of Microsoft Office. If they do not match, you may see an error related to ActiveX controls. (See [http://www.reliasoft.com/support/rs20024.htm ReliaSoft KB article RS20024].)
==Prerequisites==
*'''Getting the latest version'''
:The ReliaSoft API consists of a library file that contains the classes, methods and events that provide access to ReliaSoft applications. The file is located in the folder where the ReliaSoft desktop applications are installed. By default, this folder is at "C:\Program Files\ReliaSoft\ReliaSoft 2023." For VBA, you will use the '''ReliaSoftAPI23.tlb''' file; for .NET applications, you will use the '''ReliaSoftAPI23.dll''' file. Prior to Version 2019, the files to use were SynthesisAPI.tlb (VBA) and SynthesisAPI.dll (.NET).


==Examples==
:To obtain the latest version of the library file and the ReliaSoft applications, choose '''File > Help > Check for Updates''' or download the latest version from the [https://support.hbmprenscia.com HBM Prenscia Support Portal].
Sample applications that you can test and tweak yourself are shipped by default with every Synthesis desktop application. They are available for Excel, PowerPoint and Visual Basic projects. The files are stored on your computer at C:\Users\Public\Public Documents\ReliaSoft\Examples10\API. (For Version 9, see C:\Users\Public\Public Documents\ReliaSoft\Examples\API.)


To run the Excel and PowerPoint examples, macros must be enabled. (To learn how, see this [http://office.microsoft.com/en-us/excel-help/enable-or-disable-macros-in-office-documents-HA010031071.aspx Microsoft article].)
*'''Build environment'''
:For Visual Studio projects using Version 10 or 11, at minimum you will need Visual Studio 2010 and the .NET Framework 4.0 runtime. Version 2018 and later require Visual Studio 2015 and the .NET Framework 4.6.1 developer pack and runtime. Starting in Version 2022, .NET Framework 4.8 developer pack is required.


You must also recompile the example before first use. In Excel or PowerPoint, choose '''Developer > Visual Basic'''. In the Microsoft Visual Basic for Applications window, choose '''Debug > Compile VBAProject'''.
*'''32- vs. 64-bit'''
:For VBA, the bit version of the ReliaSoft applications that you've installed must match your installed version of Microsoft Office. If they do not match, you may see an error related to ActiveX controls.  


==API Reference Documentation==
:For Visual Studio projects targeting the .NET Framework 4.5 (or later) and compiled to run an any platform (Any CPU), turn off the '''Prefer 32-bit''' property of the build configuration if you want instances of your application to run as a 64-bit process; otherwise, the application will run as a 32-bit process on both 32- and 64-bit versions of Windows. It is necessary to ensure your application bitness matches the bitness of the ReliaSoft desktop applications installed wherever your application is run due to dependencies on platform-specific libraries.
This documentation is organized by object type. For an alphabetical listing of all classes and enumerations, see [[Full Synthesis API]].


*The [[Repository_Class|Repository]] object represents a connection to a Synthesis repository. You will need to establish a connection to a Synthesis repository before you can read and/or write data to it. Once you have a connection, you can use the methods in the Repository class to update Synthesis resources, import or export data from XML files, or transfer data to the Synthesis Data Warehouse (SDW).
*'''Running API applications on a server
:If you plan to run the API on a Windows server, you must use [https://help.reliasoft.com/basics/content/reliasoft_installation_and_licensing.htm locally hosted licensing] with Prenscia Access.  


*The following objects represent a type of Synthesis resource.  
*'''Access to calculations functionality
**[[cModel Class|cModel]]
:Access to Weibull++'s analysis and plotting engines requires a ReliaSoft API license. To obtain a license, please see [https://www.hbkworld.com/en/contact-us/reliasoft-worldwide-contacts contact ReliaSoft].
**[[cAction Class|cAction]]
**[[cURD Class|cURD]]
**[[cVariable Class|cVariable]]
**[[cCrew Class|cCrew]]
**[[cPool Class|cPool]]
**[[cCorrectiveTask Class|cCorrectiveTask]]
**[[cScheduledTask Class|cScheduledTask]]
**[[cXfmeaControl Class|cXfmeaControl]]
<!--
*The following objects represent a type of analysis or folio. You would use these objects to perform analyses on external data sources; hence, a connection to a Synthesis repository is not required.
**WeibullDataSet
**ALTADataSet
**WAPlots


To specify the displayed language for the Synthesis API library, use the [[Common_Class|SynthesisAPI.SetLanguage]] common class method.
==Getting Started==
-->


====Referencing the ReliaSoft API Library File====
<!-- This "onlyinclude" section is transcluded into the API Tutorials page -->
<onlyinclude>To use the ReliaSoft API in your code, you must reference the ReliaSoft API library in your VBA or .NET projects. The file is located in the folder where the ReliaSoft desktop applications are installed. By default for Version 2023, this folder is at "C:\Program Files\ReliaSoft\ReliaSoft 2023." For VBA, you will use the '''ReliaSoftAPI23.tlb''' file; for .NET applications, you will use the '''ReliaSoftAPI23.dll''' file.


<!--  
'''To reference the library in VBA''':
The Synthesis API can be used to accomplish many of the same tasks as within Synthesis applications, and it also enables seamless integration of the Synthesis Platform with other systems within your organization—all through a programmer's own custom-developed code. This allows you to create customizable and automated solutions to reliability engineering problems by integrating Synthesis functionality into other applications.  
:#Enter the VBA environment by clicking the '''Visual Basic''' command on the Developer tab (If the Developer tab is not visible, see [https://msdn.microsoft.com/en-us/library/bb608625.aspx this Microsoft article]).
:#In the VBA environment, choose '''Tools > References'''.
:#Click '''Browse''' and find the ReliaSoftAPI23.tlb file on your computer. Click '''OK'''.  


This reference describes all of the programming elements in the API. The sample code and documentation have been prepared for .NET, VB6 and VBA development environments, and it is assumed that the reader is familiar with them.  
'''To reference the library in Visual Studio:'''
:#In the Solution Explorer, right-click the '''References''' node of your project and choose '''Add References'''.
:#In the Reference Manager window, click the '''Browse''' tab and find the ReliaSoftAPI23.dll file on your computer. Click '''OK'''.
:#Edit your project file, either directly using any text editor, or by right-clicking your project and choosing '''Unload Project''', then right-clicking your project again and choosing '''Edit Project File'''
:#Insert the following line just before the last </Project> clause (change the path if necessary):
:::
::::::<Import Project="C:\Program Files\ReliaSoft\ReliaSoft 2023\ReliaSoftAPI.targets" />
:::
:::This will ensure the required files are copied into your project’s destination folder during the build.
:#<li value="5">Save the project file. If you unloaded the project in step 3, right-click the project and choose '''Reload Project'''.</li>
</onlyinclude>
====Examples====
Sample applications that you can test and tweak yourself are included with the ReliaSoft installation. The files are stored on your computer at C:\Users\Public\Public Documents\ReliaSoft\Examples23\API.
The sample applications are available for Excel VBA and VB.NET projects. (To run the Excel examples, macros must be enabled. See [http://office.microsoft.com/en-us/excel-help/enable-or-disable-macros-in-office-documents-HA010031071.aspx this Microsoft article].)


== Requirements  ==
====Tutorials====
[[API Tutorials|Tutorials]] are available to help you learn the core objects of the ReliaSoft API and start coding right away. The tutorials include code samples for both VBA and VB.NET.


Before using the Synthesis API, note the following requirements:
==Object Library ==
Below is a summary of the core objects in the ReliaSoft API library. For an alphabetical listing of all objects in the latest version, see [[API Reference Documentation]].


*Your code must include a reference to the ReliaSoft Synthesis API Library. The library is located in the folder where ReliaSoft Synthesis is installed. By default, this folder is "C:\Program Files\ReliaSoft\Synthesis 10" (for version 9 users it is&nbsp;"C:\Program Files\ReliaSoft\Synthesis 9").
*The <code>'''[[Repository Class|Repository]]'''</code> object represents the ReliaSoft repository. All other objects use the functions in this class to read or write data to the repository. This class also contains the functions for importing/exporting XML files.  
**.NET developers – use the SynthesisAPI.dll library
**VB6 / VBA developers – use the SynthesisAPI.tlb library


*The version of the Synthesis Platform that you've installed (32- vs. 64-bit) must match your installed version of Microsoft Office. If they do not match, you may see an [http://www.reliasoft.com/support/rs20024.htm error] related to ActiveX controls.
*The following objects represent the ReliaSoft resources. Instances of each class can be used to store data for an existing or new resource.
**<code>'''[[CAction Class|cAction]]'''</code>
**<code>'''[[CCorrectiveTask Class|cCorrectiveTask]]'''</code>
**<code>'''[[CScheduledTask Class|cScheduledTask]]'''</code>
**<code>'''[[CCrew Class|cCrew]]'''</code>
**<code>'''[[CModel Class|cModel]]'''</code>
**<code>'''[[CPool Class|cPool]]'''</code>
**<code>'''[[CProfile Class|cProfile]]'''</code>
**<code>'''[[CURD Class|cURD]]'''</code>
**<code>'''[[CVariable Class|cVariable]]'''</code>
**<code>'''[[CXfmeaControl Class|cXfmeaControl]]'''</code>


== API Elements  ==
*The following objects build data sets for the Reliability Data Warehouse (RDW).
**<code>'''[[RawData Class|RawData]]'''</code> represents a single data point.
**<code>'''[[RawDataSet Class|RawDataSet]]'''</code> serves as the data container for <code>RawData</code> objects.


The Synthesis API includes a rich set of programming elements that allow you to work with any of the following components of the Synthesis Platform:
*The <code>'''[[XfmeaItem Class|XfmeaItem]]'''</code> object represents a system hierarchy item. Instances of this class can be used to store data for a system or assembly, as well as build a multi-level system configuration.


*'''[[Repository Class|Repositories]]''': Allows you to connect to a standard or enterprise Synthesis repository to access/edit repository-level information. This includes accessing/adding/modifying resources, exporting/importing BlockSim and XFRACAS XML files and exporting data to the Synthesis Data Warehouse (SDW).
*The following objects represent the FMEA records. Instances of each class can be used to store data for an existing or new FMEA analysis.  
*'''[[WeibullDataSet Class|Weibull++ Data Sets]]''': {{Template:WeibullDataSet Class.Cmt}}
**<code>'''[[XfmeaFunction Class|XfmeaFunction]]'''</code>
*'''[[ALTADataSet_Class|ALTA Data Sets]]''': {{Template:ALTADataSet Class.Cmt}}
**<code>'''[[XfmeaCause Class|XfmeaCause]]'''</code>
*'''[[WAPlots Class|Weibull++/ALTA Plots]]''': {{Template:WAPlots Class.Cmt}}
**<code>'''[[XfmeaEffect Class|XfmeaEffect]]'''</code>
*'''[[Resource Classes|Resources]]''': {{Template:Resource Classes.Cmt}}
**<code>'''[[XfmeaFailure Class|XfmeaFailure]]'''</code>
*'''[[Common Class|Displayed Language]]''': {{Template:Common Class.Cmt}}


A complete list of all the classes and enumerations in the Synthesis API is available [[Full Synthesis API|here]].  
*The <code>'''[[WeibullDataSet Class|WeibullDataSet]]'''</code> object represents a Weibull++ data sheet for life data analysis. Instances of this class are used to define a data set and fit a statistical distribution to the data.


== Application Examples  ==
*The <code>'''[[ALTADataSet Class|ALTADataSet]]'''</code> object represents an ALTA data sheet for accelerated life testing data analysis. Instances of this class are used to define a data set, and fit a distribution and life-stress relationship to the data.


'''Excel VBA Samples'''
*The <code>'''[[WAPlots Class|WAPlots]]'''</code> object represents a plot based on a <code>cModel</code>, <code>WeibullDataSet</code> or <code>ALTADataSet</code> object. Instances of this class are used to display a plot of the analysis results.
 
Use the following links to download macro-enabled Excel files (*.xlsm) that utilize the Synthesis API. Note that to run/view the underlying code, the [http://msdn.microsoft.com/en-us/library/bb608625.aspx Developer tab must be enabled] in Excel so you can enter the Visual Basic for Applications (VBA) environment by choosing '''Developer &gt; View Code'''. Also, you must have [http://office.microsoft.com/en-us/excel-help/enable-or-disable-macros-in-office-documents-HA010031071.aspx macros enabled] to run the example files. If Excel displays a warning regarding macros in these files, select to enable them.
 
*Use Synthesis analysis engines in Excel
**[http://www.reliasoft.com/synthesis/api/examples/WeibullExample.xlsm Life Data Analysis in Excel (243 KB)] ([[Life Data Analysis in Microsoft Excel - Explanation|Code explanation]])
**[http://www.reliasoft.com/synthesis/api/examples/ALTAExample.xlsm Accelerated Life Testing Analysis (ALTA) in Excel (224 KB)] ([[Accelerated Life Testing Analysis in Microsoft Excel - Explanation|Code explanation]])
*Transfer data from Excel to the Synthesis Reliability Data Warehouse (RDW)
**[http://www.reliasoft.com/synthesis/api/examples/SDW_Example_Standard.xlsm Excel to Standard Repository (2.64 MB)]
**[http://www.reliasoft.com/synthesis/api/examples/SDW_Example_Enterprise.xlsm Excel to Enterprise SQL Repository (2.64 MB)] ''Requires code modification to reference a SQL repository.''
*Use Excel to update Universal Reliability Definitions (URDs) used in BlockSim, etc.
**[http://www.reliasoft.com/synthesis/api/examples/URDExample_V10.xlsm Update URDs with Excel (108 KB)]
-->

Latest revision as of 20:00, 12 April 2024

APIWiki.png



The ReliaSoft Application Programming Interface (API) enables you to programmatically read and write data to ReliaSoft repositories, as well as analyze and plot data sets from external sources. It is provided for Visual Basic for Applications (VBA) and .NET applications, allowing you to create automated solutions using popular Microsoft Office applications, such as Excel and PowerPoint, or create custom applications for your organization.

Implementing the ReliaSoft API allows you to connect data in repositories with the systems and tools used within your organization. It provides the functionality to:

  • Transfer and synchronize data via XML
Use XML files to manage structured data (such as system hierarchies/BOMs, incidents and work orders) between ReliaSoft’s XFRACAS and a variety of different PLMs, ERPs, CMMS and other external systems. You can also use XML files to create reliability block diagrams (RBDs) in BlockSim.
  • Read/write specific data elements
Read or write data to resources (models, actions, URDs, etc.), system hierarchy items and FMEA records (causes, effects, failures, etc.). Initiate batch data processing and create custom solutions for importing/exporting data from ReliaSoft repositories, as well as load data into the Reliability Data Warehouse (RDW).
  • Obtain calculated results
Read data from published models and obtain calculated results such as reliability, probability of failure, BX% life, failure rate and mean time.
  • Analyze data
Use Weibull++'s analysis and plotting engines to analyze data from third-party sources, and incorporate the functionality into your own custom applications. (Requires a ReliaSoft API license.)

Prerequisites

  • Getting the latest version
The ReliaSoft API consists of a library file that contains the classes, methods and events that provide access to ReliaSoft applications. The file is located in the folder where the ReliaSoft desktop applications are installed. By default, this folder is at "C:\Program Files\ReliaSoft\ReliaSoft 2023." For VBA, you will use the ReliaSoftAPI23.tlb file; for .NET applications, you will use the ReliaSoftAPI23.dll file. Prior to Version 2019, the files to use were SynthesisAPI.tlb (VBA) and SynthesisAPI.dll (.NET).
To obtain the latest version of the library file and the ReliaSoft applications, choose File > Help > Check for Updates or download the latest version from the HBM Prenscia Support Portal.
  • Build environment
For Visual Studio projects using Version 10 or 11, at minimum you will need Visual Studio 2010 and the .NET Framework 4.0 runtime. Version 2018 and later require Visual Studio 2015 and the .NET Framework 4.6.1 developer pack and runtime. Starting in Version 2022, .NET Framework 4.8 developer pack is required.
  • 32- vs. 64-bit
For VBA, the bit version of the ReliaSoft applications that you've installed must match your installed version of Microsoft Office. If they do not match, you may see an error related to ActiveX controls.
For Visual Studio projects targeting the .NET Framework 4.5 (or later) and compiled to run an any platform (Any CPU), turn off the Prefer 32-bit property of the build configuration if you want instances of your application to run as a 64-bit process; otherwise, the application will run as a 32-bit process on both 32- and 64-bit versions of Windows. It is necessary to ensure your application bitness matches the bitness of the ReliaSoft desktop applications installed wherever your application is run due to dependencies on platform-specific libraries.
  • Running API applications on a server
If you plan to run the API on a Windows server, you must use locally hosted licensing with Prenscia Access.
  • Access to calculations functionality
Access to Weibull++'s analysis and plotting engines requires a ReliaSoft API license. To obtain a license, please see contact ReliaSoft.

Getting Started

Referencing the ReliaSoft API Library File

To use the ReliaSoft API in your code, you must reference the ReliaSoft API library in your VBA or .NET projects. The file is located in the folder where the ReliaSoft desktop applications are installed. By default for Version 2023, this folder is at "C:\Program Files\ReliaSoft\ReliaSoft 2023." For VBA, you will use the ReliaSoftAPI23.tlb file; for .NET applications, you will use the ReliaSoftAPI23.dll file.

To reference the library in VBA:

  1. Enter the VBA environment by clicking the Visual Basic command on the Developer tab (If the Developer tab is not visible, see this Microsoft article).
  2. In the VBA environment, choose Tools > References.
  3. Click Browse and find the ReliaSoftAPI23.tlb file on your computer. Click OK.

To reference the library in Visual Studio:

  1. In the Solution Explorer, right-click the References node of your project and choose Add References.
  2. In the Reference Manager window, click the Browse tab and find the ReliaSoftAPI23.dll file on your computer. Click OK.
  3. Edit your project file, either directly using any text editor, or by right-clicking your project and choosing Unload Project, then right-clicking your project again and choosing Edit Project File
  4. Insert the following line just before the last </Project> clause (change the path if necessary):
<Import Project="C:\Program Files\ReliaSoft\ReliaSoft 2023\ReliaSoftAPI.targets" />
This will ensure the required files are copied into your project’s destination folder during the build.
  1. Save the project file. If you unloaded the project in step 3, right-click the project and choose Reload Project.

Examples

Sample applications that you can test and tweak yourself are included with the ReliaSoft installation. The files are stored on your computer at C:\Users\Public\Public Documents\ReliaSoft\Examples23\API.

The sample applications are available for Excel VBA and VB.NET projects. (To run the Excel examples, macros must be enabled. See this Microsoft article.)

Tutorials

Tutorials are available to help you learn the core objects of the ReliaSoft API and start coding right away. The tutorials include code samples for both VBA and VB.NET.

Object Library

Below is a summary of the core objects in the ReliaSoft API library. For an alphabetical listing of all objects in the latest version, see API Reference Documentation.

  • The Repository object represents the ReliaSoft repository. All other objects use the functions in this class to read or write data to the repository. This class also contains the functions for importing/exporting XML files.
  • The following objects build data sets for the Reliability Data Warehouse (RDW).
    • RawData represents a single data point.
    • RawDataSet serves as the data container for RawData objects.
  • The XfmeaItem object represents a system hierarchy item. Instances of this class can be used to store data for a system or assembly, as well as build a multi-level system configuration.
  • The WeibullDataSet object represents a Weibull++ data sheet for life data analysis. Instances of this class are used to define a data set and fit a statistical distribution to the data.
  • The ALTADataSet object represents an ALTA data sheet for accelerated life testing data analysis. Instances of this class are used to define a data set, and fit a distribution and life-stress relationship to the data.
  • The WAPlots object represents a plot based on a cModel, WeibullDataSet or ALTADataSet object. Instances of this class are used to display a plot of the analysis results.