Table of Contents
RQuest Admin manual
This manual describes the admin functions of PROLIN RQuest.
You can start the admin by going to the following URL:
https://[your RQuest URL]/admin
If you start RQuest's admin module for the first time you have to complete the Admin Setup Wizard first.
1 - Dashboard
This overview shows a log of all actions that are happening in the system. If you hover over a line you will get more information of that specific entry.
2 - Settings
2.1 - Email
Here you can define a white list of domain names that are allowed to register themselves for the user frontend. You can enter several domain names by separating them with either a Space, a Comma or a Semicolon.
If a user tries to register using an email with a different domain he receives an error and can't finish his registration.
2.2 - Active Directory
The Active Directory section under Security Settings allows the Administrator to configure and enable Active Directory authentication.
The following settings need to be specified for this:
Setting | Description |
---|---|
ClientId | This value indicates the id of the client that has been setup in the ADFS settings on the server. |
Secret | The secret of the client mentioned above. |
Authority | The address where the Active directory is running. |
First, some setup is needed on the Active Directory side using the Windows ADFS tool. Note that the minimum requirements for using Active Directory are ADFS 4.0 (2016) and Windows Server 2016.
1. An Application Group needs to be created. The name doesn't matter.
2. Then an application needs to be added (again name doesn't matter), where the type of the application should be Server Application:
3. Two redirect uri's are needed; one for sign-in and one for sign-out.
sign-in | https://[APPNAME].rquest.prolin.com/login/signin-adfs |
sign-out | https://[APPNAME].rquest.prolin.com/login/signout-callback-adfs |
4. A Client Identifier is automatically generated. This value is later needed for setting up AD in the Admin Service.
5. A secret needs to be generated. This value is later needed for setting up AD in the Admin Service.
Then in the Admin Service, the generated Client Id from step 4 above, needs to be filled in into the Active Directory Client Id field. The generated secret from step 5 above needs to be filled in into the Active Directory Client Secret field. Lastly, the Active Directory Authority field in the Admin Service needs to contain the address where Active Directory is running.
2.3 - Agent Client Access
This string is unique per RQuest environment and needs to be entered when an agent is configured.
3 - Appearance
4 - Users
In this function administrators can view which users are registered in the system. They can also delete users here. The admin user can not be deleted.
5 - Roles
At this moment there is only one extra role: administrator. This role is automatically linked to the admin user.
6 - Templates
Templates are the base of the system. They allow you to define what kind of information is asked from the user and what is send to the external system. When available you can also define what workflow is used for the template and what policies apply to this template.
A template has some general information and can have one or more revisions. The revisions mechanism enables you to make changes to a template and still make sure that all templates are handled correctly.
You can create a new template by clicking on the (+) button or edit an existing one by clicking on the edit button.
6.1 - Edit template
Name | The name of the template |
Description | A short description of the template |
Categories | The category or categories where this template is visible. This relates to the blocks that are visible on the user front end |
Press the Save button to save your changes or the Close button to disregard you changes.
6.2 - Import template
You can import templates that have be created by an export or by creating a template text file manually. Press the Import button, select the file you want to import. The import starts automatically after selecting the file.
Here you can download an example template file.
6.3 - Template revisions
A template can have several revisions. Every revision has one of the following statuses:
Draft | Revisions having the Draft status can be edited by the administrator, but cannot be used by your users yet. |
Published | There can only be one revision having this status. This is the revision that is currently active allowing your users to create new requests with it. |
Discontinued | A revision with this status has been published before, but a newer revision is published so this one cannot be used anymore to create new requests. The revision is automatically preserved by the system and cannot be deleted, because any request that was created with this revision will continue to use it. |
Obsolete | This status indicates that the revision has been published before, but has been superseded by a newer published revision. This is similar to the Discontinued status, however with the difference that no requests have ever been created with this revision and it is therefore safe for deletion. |
6.3.1 - New revision
You can add a new revision by clicking on the (+) button. You will then start with a completely empty revision form.
6.3.2 - Clone revision
This command allows you to create a new revision having the Draft status, based on the currently selected revision. While this is typically useful for creating a new revision based on the one that is currently published, it can also be used on any of the other revisions.
This will open the revision form with all values filled in from the revision that you have cloned. If you decide that you don't want to save this revision, press the Close button. If you, at any point, press the Save button, the cloned revision is saved having the Draft status.
6.3.3 - Edit revision
As long as a revision has status Draft, you can edit it by clicking the Edit button.
Published, Discontinued and Obsolete revisions cannot be edited.
6.3.4 - Publish revision
If you are satisfied with a revision you can publish it so it can be used by users in the frontend. To do this, select the revision you want to publish and press the Publish button.
The status of the revision you published is changed to Published and the status of the former revision that was published is changed to Discontinued.
6.3.5 - Editing revisions
The following description is about the values you can fill in when creating or editing a revision.
The revision form contains three tab pages:
- Schema
- Design
- Details
Schema
Subject
The Subject field is used in RQuest to identify the request (for instance in the My Requests view). You can use expressions in this field to construct a dynamic string containing text and field values.
Some examples:
'Ordered new phone "' + [model] + '"' [Quantity] * [UnitPrice] * (1 - [BonusAmount]) [FirstName] + ' ' + [LastName]
Read more details on how to use expressions here.
The first example will result in the following column in the My Request page:
Properties
On the Schema tab you also define the properties that can be used in this revision. Properties are used to define the individual fields of the data structure represented by the template revision. As such they can be used to capture information from the user (using a Form), but also in workflow logic. Note that you are completely free how to model this data structure.
You can create, modify and delete properties using the buttons in the toolbar.
Every property has the following fields:
Field | Description |
---|---|
Name | The name of the property. |
Display_Name | The name used on the UI for this property. |
Type | The type of the property. Choices are: Boolean, Decimal, Double, Guid, Int32, Int64, String, Duration, Date and DateTime. |
Is Calculated | Define whether or not the fields content should be filled using an expression. If this checkbox is selected specific information about the Calculated field can be entered. See description below. |
Data Source | The Data Source that should be used for this field. |
Default Value | Default value of the field. Make sure to enclose strings in single quotes. |
Constraints | Specify the constraints that are valid for this property. See the table below for further information. |
Help Text | This text is shown when a user sets focus to the field in a form that uses this property. |
Calculated Field properties
If the “Is Calculated” checkbox is checked two new fields replace the fields “Data Source” and “Default Value”:
Field | Description |
---|---|
Evaluation Scope | Defines when the calculation has to be done. The options are: |
OnPropertyChange - If field in the form are used in the expression the value is changed when the fields are changed. | |
OnSubmit - Calculation will be done when the form is submitted. | |
OnCreate - Calculation will be done when the form is opened. | |
Calculation Expression | A regular expression. Click here for more details about regular expressions. |
Constraints
Constraint | Description |
---|---|
ReadOnly | Indicates that the property read-only. If the property is used in a Form, the user cannot change its value. |
Mandatory | Indicates that the property requires a value before the owning request can be submitted. |
Length | Indicates a maximum length and is typically used for String properties only. |
Design - Form, Workflow & Policy
Form | Customize the layout and fields of the form that is shown to create or edit a request. |
Workflow Function not available yet | Customize the fulfillment workflow that is executed for individual requests. |
Policies Function not available yet | Define the policies that are applied to requests created with this template. |
When you click on the Form button you open the form maintenance screen. A form consists of 3 components: pages, panels and fields. A page can have one or more panels and each panel can have one or more fields.
You can add pages, panels and fields using the dropdown field in the left bottom of the screen.
A Page has the following properties:
Name | This is the internal name of the page. |
Display Name | This is the name that is shown in the UI. |
A Panel has the following properties:
Name | This is the internal name of the panel. |
Display Name | This is the name that is shown in the UI. |
A Field has the following properties:
Name | This is the internal name of the field. | |
Display Name | This is the name that is shown in the UI. | |
Data Member | The link to the property of this template. | |
Editor Type | The type of UI editor that is used for this field. The values depend on the type of the property. |
|
String | TextBox, MemoBox, LookupBox, TagBox, DropDownListBox | |
Date | DateTimeBox | |
Boolean | CheckBox, Switch | |
Decimal, Double, Int32, Int64 | NumberBox, LookUpBox, TagBox, DropDownListBox | |
Duration | DurationBox |
If you choose one of the following editor types: LookUpBox, TagBox or DropDownListBox you will see four extra fields. The first three show the Data Source values that are linked to the property. The fourth (Search) need to be filled in here.
Data source name | The name of the data source |
Value expression | The name of the column of which the value is used to store with the request |
Display expression | The name of the column of which the value is used to display in the UI |
Search expression | The name of the column of which the value is used when searching in the list |
Using the example values in the screen print above and using the following datasource:
Will result in this dropdown list in the request form:
And storing SINGLE, DEPARTMENT or ORGANIZATION (depending on your choice) in the database. This value is what is being sent to the external system.
Preview
When designing a Form you can look at how the actual form will look like by clicking in the Preview button. This shows the form as it will later be seen by the users.
Details
7 - Policies
TBD
8 - Categories
TBD
9 - Data Sources
10 - Services
11 - Channels
A channel provides the necessary communication infrastructure and allows you to route request-specific messages to an external service via one or more on-premise installed agents.
11.1 - General
11.2 - Services
11.3 - Agents
Here you'll see all agents that have been subscribed to the currently selected channel within your RQuest environment. Agents are automatically added to this list after they have been downloaded, installed and correctly configured.
An agent can have one of the following connection statuses:
Status | Description |
---|---|
Offline | The agent has been subscribed successfully, but is currently not running. |
Online | The agent is running and fully operational. |
Clicking the Download Agent button opens a dialog with brief instructions on how to download, install and configure the agent software. Press the Download button to start downloading the zip file and follow the provided instructions.
11.3.1 - Install
Prerequisites: .NET Core runtime: https://dotnet.microsoft.com/download/dotnet-core/3.1
Download the agent and unzip to a folder of choice on your on-premise Windows machine:
11.3.2 - Configure and Start
Before configuring the RQuest agent, please make sure that the following Internet domains are not blocked by your firewall:
Domain | Ports | Remarks |
---|---|---|
<MyApp>.rquest.prolin.com | 443 | |
request-biz-*.servicebus.windows.net | 443, 5671 | Depending on your firewall the wildcard may work just fine. If you prefer to use an exact address please consult PROLIN support. |
To configure the RQuest agent, open a Command Prompt, navigate to the folder where the agent resides and type the following command:
RQuest.Agent configure
During configuration you will be asked to provide the following information:
Input Value | Description |
---|---|
Endpoint address | The base address of the remote RQuest service. Typically this corresponds with the public address of your RQuest environment, for example: https://myapp.rquest.prolin.com |
Client secret | The unique client secret for the Agent which can be obtained from the Security page in the RQuest Admin Console. |
Channel | The name of the integration channel to subscribe to. Defaults to “default”. |
Agent | Optional agent name. Defaults to the computer name hosting the Agent. This name will be shown on the Agents page of the Channels section in the Administrator console and allows you to identify the agent in case you have installed multiple instances. |
Once the configuration has been completed, you can verify that it's working correctly using the following command:
RQuest.Agent run
If you don't see any errors in the output the RQuest agent is working properly and you can stop it by pressing Ctrl+C. If errors are shown and you experience connection problems with your configured agent, please refer to the Azure Service Bus Troubleshooting Guide.
After you have verified that the agent is working properly, you can install and run the agent as a Windows service as follows:
RQuest.Agent install RQuest.Agent start
11.3.3 - Stop and Uninstall
To stop and uninstall the agent type the following commands:
RQuest.Agent stop RQuest.Agent uninstall
In addition to the previous two commands, remove the agent's subscription as follows:
RQuest.Agent configure /remove
11.3.4 - Other Options
For more information type:
RQuest.Agent help
11.4 - Metrics
12 - Bindings
TBD