Admin operations

Introduction

All new endpoints from the admin group are described below. Their common feature is that there is the word admin in routing, which means that the endpoint requires administrative scope, and thus an App context application. Note that they no longer need administrative privileges beside the scopes, more about scopes can be found in this article. In each group, there will be a link to the documentation, but if you have access to the BPS environment, you can try it in swagger at {addressPortal}/api, e.g., https://example.webcon.pl/api. Most of these endpoints can be found in the PublicApiAdmin group; only the endpoints related to privileges are in the PublicApiMetadata group. Under each endpoint, there is a set of scopes that allow you to use them. Having one of them is enough to use the endpoint.

Privileges

Endpoints that allow you to control applications’ privileges, processes, and document types. These endpoints are the only exception to the rule, they are in the metadata group and require a different type of scopes. Each object class has a GET endpoint returning a list of privileges and POST endpoints with add and remove methods. You can read more about how privileges work in the article WEBCON BPS Designer Studio privileges

The exact data model is available in swagger or the documentation

• Applications

  • GET /api/data/v6.0/db/{dbId}/applications/{idguid}/admin/privileges [Scopes: App.Metadata.Read; App.Metadata.ReadWrite] - returns a list of privileges, each containing bpsId and username and level: Administrator, PortalDesigner, MetadataAccess, ReadOnly
  • POST /api/data/v6.0/db/{dbId}/applications/{idguid}/admin/privileges/add [Scopes: App.Metadata.ReadWrite]
  • POST /api/data/v6.0/db/{dbId}/applications/{idguid}/admin/privileges/remove [Scopes: App.Metadata.ReadWrite]- are used to add/remove individual privileges, the method needs to be passed the user's bpsId and one of the levels described above

• Processes

  • GET /api/data/v6.0/db/{dbId}/processes/{idguid}/admin/privileges [Scopes: App.Metadata.Read; App.Metadata.ReadWrite] - similarly to applications, it returns a list of privileges, the difference is the available levels: Administrator, Modify, Start, ReadOnly, ReadOnlyWithoutAttachments, ManageArchive. They correspond to what can be set up in the Studio
  • POST /api/data/v6.0/db/{dbId}/processes/{idguid}/admin/privileges/add [Scopes: App.Metadata.ReadWrite]
  • POST /api/data/v6.0/db/{dbId}/processes/{idguid}/admin/privileges/remove [Scopes: App.Metadata.ReadWrite] - endpoints for adding / removing privileges that behave in the same way as in applications. However, there is one difference: you can additionally specify within which business entities the privileges will be added; the company object, with standard ID and GUID fields, is responsible for this.

• Associated form types They work in the same way as processes and use the same data model

  • GET /api/data/v6.0/db/{dbId}/workflows/{wfIdguid}/associatedFormTypes/{idguid}/admin/privileges [Scopes: App.Metadata.Read; App.Metadata.ReadWrite]
  • POST /api/data/v6.0/db/{dbId}/workflows/{wfIdguid}/associatedFormTypes/{idguid}/admin/privileges/add [Scopes: App.Metadata.ReadWrite]
  • POST /api/data/v6.0/db/{dbId}/workflows/{wfIdguid}/associatedFormTypes/{idguid}/admin/privileges/remove [Scopes: App.Metadata.ReadWrite]

Connections

This is a set of endpoints that allows you to manage connections. You can download their metadata, create new or edit existing ones.

Documentation

You can use the following endpoints:

• GET /api/data/v6.0/db/{dbId}/admin/connections [Scopes: Admin.Read.All; Admin.ReadWrite.All; Admin.Connections.Read; Admin.Connections.ReadWrite]- allows you to download a list of all configured connections. You will get a set of basic metadata for each connection - ID, name, GUID, and type. Additionally, each connection will return HATEOAS links.

• GET /api/data/v6.0/db/{dbId}/admin/connections/{idguid} [Scopes: Admin.Read.All; Admin.ReadWrite.All; Admin.Connections.Read; Admin.Connections.ReadWrite] - allows you to get the exact data of one connection indicated by ID or GUID. In addition to the general data from the previous endpoint, it also returns a node appropriate to the type. Each of them will return the common, dev, test, and prod nodes provided that they have broken configuration inheritance. In addition, these environments will return the breakInheritance flag to draw your attention to the fact that the configuration inheritance is broken. You must remember that no connection will return sensitive login details, such as login or password. Each type will return a different set of form fields described below:

  • sql - for each environment, you get the server, database, and integratedAuthentication
  • oracle - each environment returns serviceName and integratedAuthentication
  • soap - returns url, skipHttpsCertificateValidation and keepAlive flags, and enum binding which can take one of the listed values: HttpSecurityNone, HttpBasic, HttpNtlm, HttpsBasic, HttpsNoCredentials
  • rest - returns authenticationUrl, baseUrl, flag skipHttpsCertificateValidation and enums authentication (Anonymous, NT, MicrosoftDynamics365, Salesforce, WEBCONBPS, MicrosoftGraph, MicrosoftDynamics365OnPremises) and connectAs (Application, User)
  • sharepoint - returns url and enum environment (Local, Sharepoint2013, Sharepoint2016, Sharepoint2019, SharepointOnline), credentials (ServiceAccoount, UserDefined, CurrentUser, BPS App)

• POST /api/data/v6.0/db/{dbId}/admin/connections [Scopes: Admin.ReadWrite.All; Admin.Connections.ReadWrite] - allows you to create one of the connection types listed above. At first glance, the model may seem complicated. However, in one request, you will only pass one object with its corresponding data type. The individual properties and their requiredness correspond to those available in Designer Studio. The POST and PATCH methods extend the model from the GET method to include the possibility of passing login credentials.

• PATCH /api/data/v6.0/db/{dbId}/admin/connections/{idguid} [Scopes: Admin.ReadWrite.All; Admin.Connections.ReadWrite] - allows you to modify the data of the selected connection, the model and principle of operation is analogous to the POST method.

Constants

This is a set of endpoints for managing global and process constants. It implements a standard set of endpoints for download, creation, and editing.

Documentation

• Getting a list of constants

  • GET /api/data/v6.0/db/{dbId}/admin/constants [Scopes: Admin.Read.All; Admin.ReadWrite.All; Admin.Constants.Read; Admin.Constants.ReadWrite] - returns all global constants
  • GET /api/data/v6.0/db/{dbId}/processes/{procIdguid}/admin/constants [Scopes: App.Metadata.Read; App.Metadata.ReadWrite] - returns a list of constants for a given process

  Endpoints return the basic information for each constant as well as a HATEOAS link to the detailed data.

• Getting the details of the constant

  • GET /api/data/v6.0/db/{dbId}/admin/constants/{idguid} [Scopes: Admin.Read.All; Admin.ReadWrite.All; Admin.Constants.Read; Admin.Constants.ReadWrite]
  • GET /api/data/v6.0/db/{dbId}/processes/{procIdguid}/admin/constants/{idguid} [Scopes: App.Metadata.Read; App.Metadata.ReadWrite]

  They also return basic data - ID, GUID, and name. Additionally, they return the ID and name of the group, description, and values for particular environments. You will get the environments as objects named common, dev, test, and prod. All of them will return value as a string and the breakInheritance flag ( does not apply to common).

• Create and update

  Create:

  • POST /api/data/v6.0/db/{dbId}/admin/constants [Scopes: Admin.ReadWrite.All; Admin.Constants.ReadWrite]
  • POST /api/data/v6.0/db/{dbId}/processes/{procIdguid}/admin/constants [Scopes: App.Metadata.ReadWrite]

  Update:

  • PATCH /api/data/v6.0/db/{dbId}/admin/constants/{idguid} [Scopes: Admin.ReadWrite.All; Admin.Constants.ReadWrite]
  • PATCH /api/data/v6.0/db/{dbId}/processes/{procIdguid}/admin/constants/{idguid} [Scopes: App.Metadata.ReadWrite]

  The following fields are required at the creation step: name, common, and its value. Additionally, if the inheritance is broken for any of the environments, its value should also be passed. Note that an empty string is a valid value.

  To clear the values for any environment, you need to restore inheritance for it. Then, you should pass an object appropriate for the environment, for example json {dev: {breakInheritance = false}} .

  Updating an environment in which the inheritance is not broken will be ignored.

  To get an endpoint from a group, you need to send the property groupId with a null value when editing. However, if you do not want to edit the group, do not send this property.

  If another user checks out a given process, you will get a 409 error when creating or editing a constant.

Groups and users

A group that allows you to operate on external users. It will enable you to use the CRUD methods. All endpoints except GETs queue to sync on the site; it usually takes no more than a few seconds to sync. After that the user can be used in the system.

Documentation

• GET /api/data/v6.0/admin/users [Scopes: Admin.Read.All; Admin.ReadWrite.All; Admin.Users.Read; Admin.Users.ReadWrite] - returns a list of all external users; the model contains basic information about the user and the synchronization status by the service. Additionally, the endpoint supports pagination

• GET /api/data/v6.0/admin/users/{bpsId} [Scopes: Admin.Read.All; Admin.ReadWrite.All; Admin.Users.Read; Admin.Users.ReadWrite] - returns information about a specific user indicated by bpsId

• POST /api/data/v6.0/admin/users/{bpsId} [Scopes: Admin.ReadWrite.All; Admin.Users.ReadWrite] - allows you to create a new user

• PATCH /api/data/v6.0/admin/users/{bpsId} [Scopes: Admin.ReadWrite.All; Admin.Users.ReadWrite] - allows you to modify the data of the indicated user, you can change everything except BpsId

• DELETE /api/data/v6.0/admin/users/{bpsId} [Scopes: Admin.ReadWrite.All; Admin.Users.ReadWrite] - deletes a given user

• GET /api/data/v6.0/admin/groups [Scopes: Admin.Read.All; Admin.ReadWrite.All; Admin.Groups.Read; Admin.Groups.ReadWrite] - returns a list of all BPS groups; the model is an array of basic group information. Additionally, the endpoint supports pagination

• GET /api/data/v6.0/admin/groups/{bpsId} [Scopes: Admin.Read.All; Admin.ReadWrite.All; Admin.Groups.Read; Admin.Groups.ReadWrite] - returns information about a specific group indicated by bpsId and its members

• POST /api/data/v6.0/admin/groups [Scopes: Admin.ReadWrite.All; Admin.Groups.ReadWrite] - allows you to create a new group

• PATCH /api/data/v6.0/admin/groups/{bpsId} [Scopes: Admin.ReadWrite.All; Admin.Groups.ReadWrite] - allows you to modify the metadata of the indicated group. Management of group members is available on separate endpoints

• POST /api/data/v6.0/admin/groups/{bpsId}/members/add [Scopes: Admin.ReadWrite.All; Admin.Groups.ReadWrite] - allows you to add new group members

• POST /api/data/v6.0/admin/groups/{bpsId}/members/remove [Scopes: Admin.ReadWrite.All; Admin.Groups.ReadWrite] - allows you to remove specific group members

• DELETE /api/data/v6.0/admin/groups/{bpsId} [Scopes: Admin.ReadWrite.All; Admin.Groups.ReadWrite] - deletes a given group

Licenses

This is a set of endpoints available only in the Cloud installation. It allows you to use the API to manage the licenses available in the admin panel. The available methods will enable you to retrieve information about licenses, add them and delete them.

Documentation

• GET /api/data/v6.0/admin/licenses [Scopes: Admin.Read.All; Admin.ReadWrite.All; Admin.Licenses.Read; Admin.Licenses.ReadWrite] - returns all currently assigned licenses as a user list with bpsId, name and license types

• GET /api/data/v6.0/admin/licenses/{bpsId} [Scopes: Admin.Read.All; Admin.ReadWrite.All; Admin.Licenses.Read; Admin.Licenses.ReadWrite] - allows you to check if the user with a specific bpsId has any license assigned

• GET /api/data/v6.0/admin/licenses/summary [Scopes: Admin.Read.All; Admin.ReadWrite.All; Admin.Licenses.Read; Admin.Licenses.ReadWrite] - returns a list of available and used licenses for each type

• POST /api/data/v6.0/admin/licenses/assign [Scopes: Admin.ReadWrite.All; Admin.Licenses.ReadWrite] - is used to assign and remove licenses. You can pass to it the bpsId collection and license types to be changed.

Businessentities

Two endpoints that will allow you to retrieve information about business entities.

Documentation

• GET /api/data/v6.0/admin/db/{dbId}/businessentities [Admin.ReadWrite.All; Admin.Read.All; Admin.BusinessEntities.Read] - returns a list of business entities with their basic information

• GET /api/data/v6.0/admin/db/{dbId}/businessentities/{idguid} [Admin.ReadWrite.All; Admin.Read.All; Admin.BusinessEntities.Read] - a set of all data for the selected business entity

Substitutions

Set of endpoints for managing user substitutions.

Documentation

• GET /api/data/v6.0/admin/substitutions [Admin.Substitutions.Read; Admin.Substitutions.ReadWrite; Admin.Read.All; Admin.ReadWrite.All] - return all substitutions for the person passed in the originalPerson query parameter

• GET /api/data/v6.0/admin/substitutions/{id} [Admin.Substitutions.Read; Admin.Substitutions.ReadWrite; Admin.Read.All; Admin.ReadWrite.All] - return substitution with given id

• POST /api/data/v6.0/admin/substitutions [Admin.Substitutions.ReadWrite; Admin.ReadWrite.All] - allows you to create a new substitutions based on the provided parameters

• PATCH /api/data/v6.0/admin/substitutions [Admin.Substitutions.ReadWrite; Admin.ReadWrite.All] - updates selected substitiution

• DELETE /api/data/v6.0/admin/substitutions [Admin.Substitutions.ReadWrite; Admin.ReadWrite.All] - deletes selected substitution.