Getting Started¶

Introduction¶

Every three-tier TcPCM installation runs a REST server, that can be used to access data in TcPCM without the need of the rich client. It can be used to import data as well.

REST API Setup¶

License¶

Endpoints (features) that export data require purchasing the license:

PPC10029 - Bulk Export API of Dynamic Calculations

Other API endpoints do not require a specific license.

User rights¶

To be able to interact with the REST API, the users need to have the “Manage REST-API” permission granted through a role assignment with such permission.

Add client information¶

One part of the security concept is the configuration of API clients (not users) that are allowed to interact with the REST API.

It is recommended to create separate clients for major versions of connection applications, so that - in case of need – obsolete versions can be prevented from connecting.

TcPCM 2412 and newer¶

Add a client via "Administration -> Manage Rest API Clients".

After adding a client you need to store the secret safely on your client for a valid authentication.

2406 and before¶

In the database is a table which is called “TcPCM.OAuthClients”. The following image shows a sample record for a client called “TcPCM” with secret “A980XXXX- XXXX-XXXX-XXXX-XXXXXXXXXXXX”.

General concepts¶

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

Testing the REST API¶

The REST API can be tested via the provided Postman query collection or any other REST API capable tool.

Ping¶

The easiest way to test the connection to the API is to use a ping call. It is a quick response so that the developer can verify that the server is running and the connection to the API works.

Authentication¶

Authentication using TcPCM already existing authentication methods¶

TcPCM supports three different login flows:

1. Resource Owner Password flow: Use the username and password with the grant_type password and authenticatorId Siemens.TCPCM.AuthenticationMethod.TcPCM or Siemens.TCPCM.AuthenticationMethod.Windows.

2. Token Exchange flow: Use the subject_token_type and subject_token with the grant_type urn:ietf:params:oauth:grant-type:token-exchange and authenticatorId Siemens.TCPCM.AuthenticationMethod.SamAuth.

3. Custom flow: Use the tcpcmSessionKey with the grant_type applicationSession without authenticatorId.

Authentication is done by calling the /token endpoint. The client_id and client_secret must be passed as described in the client setup section.

In a successful response, the access_token (also called bearer token) is needed for subsequent calls to the REST API endpoints.

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. The client_id and client_secret are still required.

The 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 the refresh_token and access_token as parameters.

General message structure¶

Standard messages are protected by using the bearer token authentication.

Request¶

To perform a request, a header and a body (except GET endpoints) must be provided.

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

Please note, the space between Bearer and the access_token. 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. 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

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:

After a successful export, an example of data is