Knowledge base PIX - Master

Меню

Interacting with PIX Master using API

Connecting to Swagger

Swagger is a tool for describing API functions.
No special knowledge is needed to generate requests in Swagger - all you have to do is specify the necessary parameters.

Connect to Swagger
In the appsettings.json file (C:\Master\appsettings.json) in the field UseSwagger set the true value:

On Linux you must also open /etc/systemd/system/Master.service and in the field Environment change the Production to Development.

After that restart the server:

Open Swagger
Open Master and add /swagger at the end of URL:

To generate a request, select the desired request type and click Try it out.

Now you should be able to (1) set the values and (2) execute a request:

Token API

Generates a unique token to interact with the PIX Master.

Note! A token is valid for 2 hours.

API-requests are easy to make in Swagger (instructions on how to connect).
Click Try it out in the upper right corner, the login and password fields for the PIX Master will be displayed.

After confirmation (Execute) the generated API request (1, 2) and a
response to the "access_token" request (3) will be displayed.

Example request:


//Replace username and password
//CURL
curl -X 'POST' \
  'https://nb063319.int.bit.ru:44300/api/Token?username=admin&password=Admin1Default%40' \
  -H 'accept: */*' \
  -d ''

//Request URL
"https://nb063319.int.bit.ru:44300/api/Token?username=admin&password=Admin1Default%40"

A token can be received without authorization, so Swagger immediately provides the result of the request (3).

For example, you can use Postman (note that it must be installed).
To receive a token, select the POST command and insert the URL generated in Swagger.
If an error (1) occurs after sending the request, disable certificate validation (2).

We get the access_token, which we will need to make other requests.

Tasks Api

Get a list of tasks
/
Start a task by ID
/
Start a task by name
/
Stop a task

API-requests are easy to make in Swagger (instructions, on how to connect).

Get a list of tasks. Works for versions of Master after 1.18.
To get a list of all tasks, enter the following URL to connect to the Master:


// Provide a link to start the Master

// URL
'"A-link-for-working-with-Master"/api/Tasks/GetTaskList'

You can use Postman to send API requests (note that it must be installed).
To do this (1) select request type (GET), insert the generated URL and authorize with a token (API for token request).

In response we get JSON with all the information about tasks.

Start a task by ID. In order to make a request in Swagger, click Try it out in the upper right corner. A field for entering task ID will be displayed. You can find the task ID in the Master or use previous request to get a list of tasks.

After confirmation (Execute) the generated API request will be displayed.

You can use a request template, specifying the necessary values in it:


// Specify the URL to start the Master and the task ID (without quotes)
// CURL
curl -X 'POST' \
  '"A-link-for-working-with-Master"/api/Tasks/StartTask?taskId="ID-of-a-task"' \
  -H 'accept: */*' \
  -d ''

// URL
'"A-link-for-working-with-Master"/api/Tasks/StartTask?taskId="ID-of-a-task"'

To send a request from Postman (1), select the request type (POST), insert the generated URL and authorize with a token (API for token request).

After executing the API request you should get an encoded response:

Start a task by name. Works for versions of Master after 1.18.
To start the task by name specify the name in the URL:


// Specify the URL to start the Master and the name of a task

// URL
'"A-link-for-working-with-Master"/api/Tasks/StartTask?taskName=name'

Starting a task from Postman would then look like this:

Stop a task. Enter the task ID.

After confirmation (Execute) the generated API request will be displayed.


// Specify the URL to start the Master and the task ID (without quotes)
// CURL
curl -X 'POST' \
  '"A-link-for-working-with-Master"/api/Tasks/StopTask?taskId="ID-of-a-task"' \
  -H 'accept: */*' \
  -d ''

// URL
'"A-link-for-working-with-Master"/api/Tasks/StopTask?taskId="ID-of-a-task"'

Processes API

Start a process in PIX Master.

API-requests are easy to make in Swagger (instructions on how to connect).
Start a process. Press Try it out in the upper right corner. A field for process ID will be displayed. You can find the process ID in the database you are using, for example, PostgreSQL.

After confirmation (Execute) the generated API request will be displayed.

Swagger automatically generates a URL.
You may use the following code, specifying the URL to start the master and task ID (without quotes):


// CURL
curl -X 'POST' \
  '"A-link-for-working-with-Master"/api/Processes/StartProcess?processId="ID-of-a-process"' \
  -H 'accept: */*' \
  -d ''

// URL
'"A-link-for-working-with-Master"/api/Processes/StartProcess?processId="ID-of-a-process"'

You can use Postman to send API requests (note that it must be installed).
To do this authorize with a token (API for token request), select request type (POST) and paste the URL generated in Swagger.

A method for stopping a process in Master
POST - API method:


/api/Processes/StopProcess?processId={processId}.

The required parameter processId contains process identifier value.
When the method is executed, the running process with the specified processId stops. Process status changes from InProgress to Canceled.

This method could be used to:

stop a process that handles data queues and waits for items to appear in the queue;
free up a robot's license instance to perform higher-priority tasks.

Data API

Get/set data values.

API-requests are easy to make in Swagger (instructions on how to connect).
4 options are available:

Get the data by identifier.

To generate a request in Swagger, you must specify the data ID.
You can input the needed values in the generated request:


//Curl
curl -X 'GET' \
  '"A-link-for-working-with-Master"/api/Data/GetValueById?dataId=7' \
  -H 'accept: text/plain'

//Request URL
"A-link-for-working-with-Master"/api/Data/GetValueById?dataId=7

You can use Postman to send API requests (note that it must be installed).
To do this (1) select request type (GET), insert the generated URL and (2-3) authorize with a token (API for token request).

As a result, we get the value.

Get the data by key.

To make a request in Swagger, you must specify a data key.
You can input the desired values (reference to the Master and the key) in the generated request:


//Curl
  '"A-link-for-working-with-Master"/api/Data/GetValueByKey?key=Key' \
  -H 'accept: text/plain'

//Request URL
"A-link-for-working-with-Master"/api/Data/GetValueByKey?key=Key

Set the data values by identifier.

To make a request in Swagger, you must specify the data ID and the value to be set.

You can input the desired values (a link to interact with Master, ID and value) in the generated request:


//Curl
  '"A-link-for-working-with-Master"/api/Data/SetValueById?dataId=1&value=Value' \
  -H 'accept: */*' \
  -d ''

//Request URL
"A-link-for-working-with-Master"/api/Data/SetValueById?dataId=1&value=Value

Set the data values by key.

To make a request in Swagger, you must specify a key and a value to be set.

You can input the desired values (Master reference, key, and value) in the generated request:


//Curl
  '"A-link-for-working-with-Master"/api/Data/SetValueByKey?key=Key&value=Value' \
  -H 'accept: */*' \
  -d ''

//Request URL
"A-link-for-working-with-Master"/api/Data/SetValueByKey?key=Key&value=Value

Use GET method to get the Data list:


/api/Data/GetDataList

Optionally you can select Data by Group by specifying the value of the groupName field.

Queues API

Work with data queues.

Status codes:

0 - New;
1 - Processing;
2 - Processed;
3 - Failed;
4 - Canceled;
5 - TimedOut;
6 - Retried.

API-requests are easy to make in Swagger (instructions on how to connect).
7 ways to interact with queues are available:

Add an item to the queue. (POST)
Swagger generates the URL automatically.
For this, specify the following parameters:

You can use a request template, specifying the necessary parameters:


//CURL
curl -X 'POST' \
  '"A-link-for-working-with-Master"/api/Queues/PushElementToQueue?queueName=queueName&data=data&priority=1&postponeDate=2022-09-21T17%3A32%3A28Z&deadlineDate=2022-09-22T17%3A32%3A28Z&comment=comment&reference=reference&isReferenceUnique=false' \
  -H 'accept: text/plain' \
  -d ''

//URL
"A-link-for-working-with-Master"/api/Queues/PushElementToQueue?queueName=queueName&data=data&priority=1&postponeDate=2022-09-21T17%3A32%3A28Z&deadlineDate=2022-09-22T17%3A32%3A28Z&comment=comment&reference=reference&isReferenceUnique=false

You can use Postman to send API requests (note that it must be installed).
To do this (1) select the POST method, insert the URL generated in Swagger and (2-3) authorize with a token (API for token request).
We will get response in the form of a key and an assigned value.

Add an item to the queue from body data. (POST)
This request is differemt from the previous one in that the value is specified in the body of a request.

You can use a request template, specifying the necessary parameters in it:


//CURL
curl -X 'POST' \
  '"A-link-for-working-with-Master"/api/Queues/PushElementToQueueFromBodyData?priority=1&isReferenceUnique=false' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d '"data"'

//URL
"A-link-for-working-with-Master"/api/Queues/PushElementToQueueFromBodyData?priority=1&isReferenceUnique=false

In Postman you must additionally specify a value in the body:

We get a JSON with the fields: key - the identifier of the queue item, value - the value of the queue item.

Get an item from a queue. (GET)

You can generate a request in Swagger by specifying the following parameters:

You can use a request template, specifying the necessary parameters in it:


//CURL
curl -X 'GET' \
  '"A-link-for-working-with-Master"/api/Queues/GetElementFromQueue?queueName=%D0%9E%D1%87%D0%B5%D1%80%D0%B5%D0%B4%D1%8C1&reference=reference&priority=1&comment=comment' \
  -H 'accept: text/plain'

//URL
"A-link-for-working-with-Master"/api/Queues/GetElementFromQueue?queueName=%D0%9E%D1%87%D0%B5%D1%80%D0%B5%D0%B4%D1%8C1&reference=reference&priority=1&comment=comment

As a result of the request we get a JSON with the fields: key - identifier of the queue item, value - value of the queue item.

Confirm processing of an item. (POST)

You can generate a request in Swagger by specifying the following parameters:

You can use a request template, specifying the necessary parameters in it:


//CURL
curl -X 'POST' \
  '"A-link-for-working-with-Master"/api/Queues/ConfirmQueueItemProcessFinish?id=1&isSuccess=true&errorComment=%D0%BD%D0%B5%20%D0%BE%D0%B1%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0%D0%BD&errorType=1' \
  -H 'accept: */*' \
  -d ''

//URL
"A-link-for-working-with-Master"/api/Queues/ConfirmQueueItemProcessFinish?id=1&isSuccess=true&errorComment=%D0%BD%D0%B5%20%D0%BE%D0%B1%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0%D0%BD&errorType=1

Note that the comment is written in a coded format.
A message saying "success" should be displayed in response to the request.

Cancel queue item. (POST)

To generate a request in Swagger, you must specify the following parameters:

You can use a request template, specifying the necessary parameters in it:


//CURL
curl -X 'POST' \
  '"A-link-for-working-with-Master"/api/Queues/CancelQueueItem?id=1&comment=comment' \
  -H 'accept: */*' \
  -d ''

//URL
"A-link-for-working-with-Master"/api/Queues/CancelQueueItem?id=1&comment=comment

Get Item Status. (GET)

To generate a request, you must specify an item ID:


//CURL
curl -X 'GET' \
  '"A-link-for-working-with-Master"/api/Queues/GetQueueItemStatus?id=1' \
  -H 'accept: text/plain'

//URL
"A-link-for-working-with-Master"/api/Queues/GetQueueItemStatus?id=1

Get queue items by filter. (GET)

To generate a request in Swagger, you must specify the following parameters:

You can use a request template, specifying the necessary parameters in it:


//CURL
curl -X 'GET' \
  '"A-link-for-working-with-Master"/api/Queues/GetQueueItemsByFilters?queueName=%D0%9E%D1%87%D0%B5%D1%80%D0%B5%D0%B4%D1%8C1&maxItems=100&statuses=new' \
  -H 'accept: text/plain'

//URL
"A-link-for-working-with-Master"/api/Queues/GetQueueItemsByFilters?queueName=%D0%9E%D1%87%D0%B5%D1%80%D0%B5%D0%B4%D1%8C1&maxItems=100&statuses=new

The result will be JSON with items matching the filters.

Scheduler API

Turn the scheduler on/off.

API-requests are easy to make in Swagger (instructions on how to connect).
ClickTry it out in the upper right corner, the fields for the parameter settings will become active.
You must specify ID and status (true - enable, false - disable) of the scheduler.

You can use the following code, specifying the URL to start the Master (without the quotes), ID and status of the scheduler:


// CURL
curl -X 'POST' \
  '"A-link-for-working-with-Master"/api/Schedulers/UpdateSchedulerStatus?id=1&isActive=true' \
  -H 'accept: */*' \
  -d ''

// URL
'"A-link-for-working-with-Master"/api/Schedulers/UpdateSchedulerStatus?id=1&isActive=true

Use a GET request to get a list of schedulers with their task and process schedules:


/api/GetSchedulersList

You can use the groupName parameter in the request to select schedulers belonging to a group.

You can use GET method to get the current status (true/false = active/inactive) of a scheduler with a specific ID:


/api/Schedulers/GetSchedulersActivityStatus

Projects API

Projects API allows you to get a list of projects, upload a new project or a new version of it and get project archive without using the web interface.

API-requests are easy to generate in Swagger (instructions on how to connect).
There are 4 ways to interact with projects:

Get a list of projects.

To make a request in Swagger, click Try it out in the upper right corner and the fields will become active.
No parameters are needed to get the list of projects.
You can use this code by specifying a link to run the Master:


// CURL
curl -X 'GET' \
  '"A-link-for-working-with-Master"/api/Projects/GetProjectList' \
  -H 'accept: */*'

// URL
"A-link-for-working-with-Master"/api/Projects/GetProjectList

You can use Postman to send API requests (note that it must be installed).
To do this, (1) authorize with a token (API for token request), (2) select the GET command and insert the URL generated in Swagger.

The result is a list of projects.

Upload a new version of the project.

The following fields must contain values to generate a request in Swagger:

You can use the following template, specifying the necessary parameters:


// CURL
curl -X 'POST' \
  '"A-link-for-working-with-Master"/api/Projects/UploadProjectVersion?projectId=1&entryPoint=entryPoint&version=version&description=description&isActual=false' \
  -H 'accept: */*' \
  -d ''
// URL
"A-link-for-working-with-Master"/api/Projects/UploadProjectVersion?projectId=1&entryPoint=entryPoint&version=version&description=description&isActual=false

Get the project archive.

To generate a request in Swagger fill in the following fields:

You can use the following template, specifying the necessary parameters:


// CURL
curl -X 'POST' \
  '"A-link-for-working-with-Master"/api/Projects/DownloadProject?projectId=1&version=version' \
  -H 'accept: text/plain' \
  -d ''

// URL
"A-link-for-working-with-Master"/api/Projects/DownloadProject?projectId=1&version=version

Upload a new project.

The following fields must contain data to generate a request in Swagger:

You can use the following template, specifying the necessary parameters:


// CURL
curl -X 'POST' \
  '"A-link-for-working-with-Master"/api/Projects/UploadProject?entryPoint=entryPoint&name=name&description=description' \
  -H 'accept: */*' \
  -d ''

// URL
"A-link-for-working-with-Master"/api/Projects/UploadProject?entryPoint=entryPoint&name=name&description=description

Method for obtaining project attributes and data.
GET - API method:


/api/Projects/GetProject?projectId={projectId}.

The value of project identifier is passed in the mandatory parameter projectId.
In response we get the IProjectInfo with the corresponding identifier, active and last updated version numbers of the project (a single version number is returned - if it is both active and last updated).

Method for checking the existence of a project.
GET - API method:


/api/Projects/ProjectExists?projectId={projectId}

The project identifier is passed in the mandatory parameter projectId.
A true value is returned if the project with the corresponding identifier exists or false if there is no such project or the user is not in a group that has access to this project.

Schedule type API

Get a list of schedule type names
GET - method


/api/ScheduleTypes/GetList?scheduleMode=Calendar

You can select by the type of schedule type in the optional scheduleMode parameter.

Get a list of dates for a schedule type with Calendar view
GET - method


/api/ScheduleTypes/GetCalendar?name=test

In the mandatory parameter name the value of the type name is passed.