The management service is a SOAP service that allows you to access and edit your repository without the use of Blueriq Encore. Most of the functionality available in Encore can be accessed via methods in the management service. This article describes how to authenticate and use the different methods of the management service.
Each request to the management service requires authentication. This can either be an OIDC access token using Bearer authentication or your username and password using BASIC authentication. It is recommended to use Bearer authentication since BASIC authentication is deprecated and will be removed in a future version.
In order to use Bearer authentication, you first need to request an access token, for example with the following HTTP request:
POST http://localhost:170/Keycloak/realms/BlueriqStudio17/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
client_id = encore &
grant_type = password &
username = admin &
password = welcome
Be aware that, as indicated by the content type, the parameters client_id, grant_type, username, and password must be provided in the x-www-form-urlencoded body of the request.
This example uses the encore client which is available by default. For production purposes it is recommended to create a dedicated client using the steps described here, with Client Authentication and Direct Access Grants enabled. With Client Authentication enabled, you also need to include the generated client secret in the request form as client_secret=<secret>
This will result in a JSON response which includes the access token, for example:
The access_token from the response must be included in the Authentication header in each of your requests to the management service, prefixed by 'Bearer ', for example:
Authentication: Bearer <access token>
If you use either SOAP UI or Postman, please consult their respective documentation pages on how to work with OIDC (or OAUTH2) authentication:
Using BASIC authentication for the Management Service is deprecated and will be removed in a future version.
In order to use BASIC authentication, you must concatenate your username and password with a colon like this: username:password and convert that to a base64 encoded value like this: dXNlcm5hbWU6cGFzc3dvcmQ= and include that in the Authentication header as follows:
Authentication: BASIC dXNlcm5hbWU6cGFzc3dvcmQ=
If you use either SOAP UI or Postman, please consult their respective documentation pages on how to use BASIC authentication.
Although many parameters in the XSD have a minOccurence of zero, almost all parameters are required. We advise to ignore the <!--Optional:--> line some tools such as SoapUI generate based on the minOccurence.
We distinguish different categories of operations:
The server will return a dependency for each element that uses the specified element. It will search through all projects and modules that are in scope for the specified element in the specified branch.
The server will return a dependency for each element that uses the specified element. It will search through all projects and modules that are in scope for the specified element in the specified branch.
Parameter
Parameter description
Required/optional
repository
the repository to search in
required
branch
the branch to search in
required
project
the project in which the element is defined
required
module
the module in which the element is defined
required
moduleElement
the element key of the element
required
If you use inheritance between modules, and specialization of elements, elements and dependencies you are looking for may react differently than expected.
Consider the following example for a module element: For a repository named ExampleRepository with a branch named ExampleBranch, with in the branch the following project structure:
project SpecificProject references GenericProject
GenericProject contains module GenericModule
GenericModule contains entity and attribute Person.Name
SpecificProject contains module SpecificModule, which includes GenericModule
SpecificModule contains container PersonView which displays Person.Name
SpecificModule contains page Overview which contains PersonView
project UnrelatedProject references none
UnrelatedProject contains module UnrelatedModule
UnrelatedModule contains entity and attribute Person.Name
UnrelatedModule contains container PersonView which displays Person.Name
If we use the GetUsedByElementsForModuleElement method with parameters: repository = ExampleRepository branch = ExampleBranch project = GenericProject module = GenericModule element key = Attribute, Person.Name
It will return a dependency for
PersonView in SpecificModule because
SpecificModule includes GenericModule
PersonView has a direct reference to Person.Name
But not for
Overview in SpecificModule because
Overview does not directly reference Person.Name
PersonView in UnrelatedModule because
there is no include between UnrelatedModule and GenericModule
The returned dependency will contain:
ReferenceType: Usage
From: ElementKeyReference
property ModuleElement will be a reference to PersonView in SpecificModule
all other properties will be null
To: ElementKeyReference
property ModuleElement will be reference Person.Name in GenericModule
all other properties will be null
Note that if Person.Name is also specialized in SpecificModule, then the dependency from PersonView in SpecificModule will refer to Person.Name in SpecificModule instead. This means the search with the given parameters will give no results: the search should also be executed for Person.Name in SpecificModule.
The server will return a description of the element with all the settings which can be configured.
For certain elements a special type is required to uniquely identify an element. An example are attributes, as an attribute with the same name can be defined multiple times for different entities. To find all of these special cases, search the wsdl for elements which have base="tns:ModuleElementKey". If you expand the example below we show how to work with attributes.
Parameter
Parameter description
Required/optional
repository
the repository to search in
required
branch
the branch to search in
required
project
the revision to be exported
required
module
the project in which the element is defined
required
moduleElement
The Name and Type of the module element which should be returned
The user can check a box to delete existing elements in the current branch that are not included in the imported branch. By checking this box, the imported branch will be identical to the exported branch.
ImportLibrary
ImportSpecification
Project Structure
GetModule
GetModules
GetPackage
GetPackages
GetProject
GetProjects
ReadLibraryMetadata
UnitTests
ExecuteAllUnitTests
Returns the result of all unit tests that are defined within a specific module scope.
Parameter
Parameter description
Required/optional
repository
The name of the repository of which the the unit tests have to be executed
required
branch
The name of the branch of which the the unit tests have to be executed
required
project
The name of the project of which the the unit tests have to be executed
required
module
The module scope of which the unit tests have to be executed. This includes tests and logic defined in the given module and all underlying modules.
Similar to ExecuteUnitTests above, but with the branch parameter replaced by a revisionId parameter to execute the tests of a particular revision. This operation is available since Blueriq 15.2.0.
This options behaves identically to GetRevisions and only exists for backwards compatibility reasons.
Parameter
Parameter description
Required/optional
repository
the repository to search in
required
branch
the branch to search in
required
startIndex
the index of the first included revision
required
amount
the number of revisions to include; a negative amount includes all revisions
required
taggedOnly
boolean flag indicating whether to include only tagged revisions
required
level
this option does not have any effect and only exists for backwards compatibility reasons
required
MergeBranch
MergeRevision
SetTags
UpdateRepository
UpdateBranch
UpdateBranchType
Other Methods
ApplyOperations
This operation allows for applying changes to the model in a particular branch. The list of operations is applied in the order in which they are provided (meaning that a creation operation of e.g. a module must precede the creation of module elements within it) and there can only be a single operation per element, otherwise this request will fail.
This request is executed atomically; either all operations succeed or the whole request is rejected.
Parameter
Parameter description
Required/optional
repository
the repository to search in
required
branch
the branch to search in
required
operations
the list of operations to apply.
required
The list of operations must contain OperationEntry elements with exactly one child element according to the type of element (ProjectOperation, PackageOperation, GlobalOperation, ModuleOperation, or ModuleElementOperation) that is being changed in that OperationEntry .
A ModuleElementOperation can either be a Create , Update , or Delete operation. In the case of Update , you need to be aware that the element is updated with the exact request data; optional elements that are omitted will be cleared instead of using their prior value as fallback. If the name of the OriginalKey and the name determined by the ModuleElement element differ then the element will be renamed, with "Update References" behavior enabled (this cannot be disabled).
The OriginalKey may take a specialized type depending on the type of element. In particular, all elements with a compound key require a dedicated type: attributes (AttributeKey), relations (RelationKey) and static instances (StaticInstanceKey). These types of key need an explicit xsi:type specification, where xsi is the XML Schema Instance namespace that needs to be declared in the SOAP envelope element (please refer to the example below).
Similarly, the ModuleElement element always needs an explicit xsi:type specification, as the ModuleElement element is of the abstract ModuleElement complex type. Hence, a concrete subtype needs to be given using xsi:type . Please be aware that the specified type name must include the namespace alias of the management service, which is ns in the example below (per the xmlns:ns declaration on the SOAP envelope element).
If no interaction occurs with a started search entry (e.g. results are not pulled via the GetAdvancedSearchResults method) for the configured timeout, the search is stopped and results are removed.
StartAdvancedSearch
This method starts a new search according to the input parameters and returns a GUID that can be further used to get the results or stop the search.
The server returns a SearchID: GUID associated with the newly started search .
Parameter
Parameter description
Required/optional
ElementName
name of the element to be searched
required
ElementTypes
array of element types that can be searched. Currently, the following global or module element types are supported : Container, Attribute, Presentation Style, Content Style, Text Item, Service Call, Flow
optional
IsInExposedFlow
boolean indicating whether the search should return information about elements in exposed flows
true: the advanced search will check if the searched element is reachable through an exposed flow and will return the information accordingly in the <IsInExposedFlow> element from the response.
false: the advanced search will not check if the searched element is reachable through an exposed flow and will return a null value in the <IsInExposedFlow> element from the response.
optional
IsSpecialized
boolean indicating whether the search should return information about specialized elements
true : the advanced search will check if the search element is specialized and return the information accordingly in the <IsSpecialized> element from the response.
false: the advanced search will not check if the search element is specialized and will return a null value in the <IsSpecialized> element from the response.
required
FullText
boolean indicating whether full-text search is enabled
optional
SearchDepth
parameter of type int, indicating the level of dependencies on which to search
optional, default value = 5
SearchIn
Array of objects composed of the name of the repository, branch and project which specifies the search location
This method stops the search for the specified Search Id, and also clears the results that are stored in the search cache in the Studio server. If the provided search id does not exist anymore, an error will be returned.
Parameter
Parameter description
Required/optional
SearchId
the GUID obtained after calling the StartAdvancedSearch method
This method returns the results associated with the input search id. The results could be partial or complete. The state of the search is indicated by the "IsSearchFinished" parameter.
Parameter
Parameter description
Required/optional
SearchId
the GUID obtained after calling the StartAdvancedSearch method