Getting Started¶

Introduction¶

Every 3-tier TcPCM installation now runs a web server, that can be used to access data in TcPCM in machine-to-machine processes. It can be also used to import data. You can find the server address by clicking in the Help->About.

This step will get you to a Swagger web page, which is a living documentation of currently existing API methods in your TcPCM version. It also provides a “try it out” functionality.

How to prepare to use the REST-API¶

License¶

Calculations/Export and ToolCalculations/CostBreakDown/Export require purchasing a license:

PPC10029 - Bulk Export API of Dynamic Calculations

Other API calls do not require a specific license.

User rights¶

Any user that will be used to authenticate towards this Web API needs to have “Manage REST-API” permission granted through a role assignment with such permission.

Add client information to the database¶

In the database is a table which is called “TcPCM.OAuthClients”. This table is used to permit access to unknown clients. Every client application that wants to use the REST- API needs to be added to that table.

We recommend creating separate records for major versions of connection applications, so that - in case of need – obsolete versions can be prevented from connecting.

The following image shows a sample record for a client called “TcPCM” with secret “A980XXXX- XXXX-XXXX-XXXX-XXXXXXXXXXXX”.

General concepts¶

The API follows the principle of "Request -> Response". Currently, TcPCM doesn't support long-running/asynchronous calls.

Testing the REST API¶

Now the API can be tested via the provided postman query collection, Python script, directly from embedded swagger web or any other REST-API capable tool.

Ping¶

The easiest way to test the connection to API is to use a Ping message. This was implemented as a quick response so that the developer can verify the connection to API works.

This can be also used to verify that the PCM web server is running.

Authentication¶

Authentication using TcPCM already existing authentication methods¶

For username/password types of the authentication, no further configuration of the TcPCM web server is needed. After the user is authenticated, the access token is provided and the username/password is no longer required through the session.

Authentication is done by calling /token endpoint. With parameters shown below in the body of the request (this is done, so that sensitive information (password, client secret, and user name) never appears in access logs).

In the response, it is possible to find the access token that will be used later to authenticate the user with subsequent messages.

The refresh token can be used to obtain a new access token after the expiration of the access token.

To do that invoke a /token with parameter request_token instead of username and password. client_id and client_secret are still required.

Refresh token is also a parameter that is needed to perform a logout.

Authentication using certificate¶

Setting up the environment for using certificate authentication is more complicated and it is not provided out of the box, see Securing with certificates.

Logout¶

It is possible to end the validity of access and refresh tokens by calling /Account/Logout and passing refresh token and access tokens as parameters.

General message structure¶

Standard (non-authentication) messages are using bearer token authentication.

Request¶

To perform a request a header and a body must be provided.

In the header, the authentication token is provided in the format of “Bearer AccessToken”.

Please note the space between Bearer and the access token. So if /token returns an access token such as ABCD your subsequent messages need to have the header parameter in the format “Bearer ABCD”. Some REST clients will do that automatically (this is the case if you are using Postman) and some do not (for example Swagger, Excel … ). Please pay attention to this parameter, since it is a source of common problems.

Calculation/Import Request¶

To import calculation data the method Calculations/Import must be called with the parameter

• Data a JArray of calculation data to import
• Guid of an import configuration that is stored in the TcPCM server database
• TargetType to define the target parent of the calculations to import (Folder, Project)
• TargetId ID of the target object
• PlantUniqueKey optional, to define the target client

The response of an import call will be a result container like on export but without data.

Response¶

The response structure depends on the message and configuration.

As an example: The response of a calculation/Export call will be a result container in the form:

Siemens.TcPCM.Server.BaseModule.Models.Responses.TcPCMResponseModel[System.Data.DataTable] 
{ 
    data (object, *optional*), 
    success (boolean, *optional*), 
    code (string, *optional*), 
    message (string, *optional*) 
} 

After successful export an example of data (automatically converted to type JArray) is