Installing the Helix Plan API Service

Follow these steps to install the Helix Plan API service:

1. Install NodeJS

Make sure that you have installed nodejs by running node -v

You can find the LTS version at https://nodejs.org/en/download/.

2. Create an SDK user

Refer to Adding an SDK user in Helix Plan in the Helix PlanWeb documentation for more information.

3. Download and unzip the Helix Plan API

You can find Helix Plan API at https://www.perforce.com/downloads/helix-plan-api.

4. Create config file

After you unzip the file you will see a configuration file named config-example.env Rename the file to ".env" and replace the options to point to the correct Hansoft server and SDK user on your environment.

Example:

# Helix Plan server connection
helixPlanHost='localhost'
helixPlanPort=50256
database='Company projects'

# SDK user that will connect to Helix Plan
sdkUser='sdk_user'
sdkPassword='password'

# The API log level
logLevel='info'

# Set to true to run the SDK in debug mode
sdkDebug=false

# The http port to use for the Helix Plan API server
port=4000

# The environment the Helix Plan API is running at, can be set to development for extra logging mechanisms
NODE_ENV=production

# Auth token validity time in seconds
tokenValidityDurationInSeconds=3600

# OPTIONAL: The data directory where the SDK stores its working data. The default is helix-plan-api-data in the application directory
#dataPath='/path-to-data-dir'

# OPTIONAL: The local path where Helix Plan documents should be stored. This directory will be used to store temporary files as well as the files in the repository. The default is helix-plan-api-document in the application directory
#documentPath='/path-to-document-dir' 

# OPTIONAL: Set to true to enable a GraphQL client https://github.com/graphql/graphql-playground (should be switched on only for development purposes)
#playground='false'  

4. Install third-party libraries

Before starting the server, run the following in the directory that contains package.json:

npm ci --omit=dev

This will install all required third-party libraries.

5. Start the server

To start the server, run the following in the directory you used in the previous step:

node dist/main

6. Verify that the service has started

If everything works, you should see something similar to this in the logs:

[Hansoft-API] Info        2023-29-02 14:32:37 [SDKService] Hansoft API 11.1.007 SDK started +1s

You have two options for how to check that the service was started successfully:

1. You can access this address in a web browser: http://localhost:4000/healthcheck
2. If you have enabled the GraphQL Playground (see the end of the config file example above), you can access it to perform tests at http://localhost:4000/graphql
Make sure to check the Docs tab on the right sidebar for more information on the available commands. This requires that you change this option in the .env file from production to development: NODE_ENV=production

Login example

The following shows a login example:

# Write your query or mutation here
mutation login($loginCredentials:LoginUserInput!){
    login(loginUserInput:$loginCredentials){
        access_token}
}

Query Variables:
{
    "loginCredentials": {
        "username": "<username>",
        "password": "<password>"
    }
}

To apply the JWT (JSON Web Token) in other GraphQL requests, add the token in the HTTP HEADERS. For example:

{
    "Authorization": "Bearer <token>"
}