Version: 7.0

Configuration

The setup of the b4A Service Portal is done in several steps. The basic configuration can be found in the configuration file config.js, which is located in the config folder. After that, it should already be possible to open the b4A Service Portal in the web browser.

Further configuration must be carried out in the Automic Automation Engine. The following section uses the example configuration from the b4A Package B4A.WEB to illustrate the configuration. From version 1.3.0 onwards, the configuration can also be carried out via the administration view in the Service Portal itself. Further details can be found in the chapter on operation.

Basic configuration

In the config.js file, you need to make some settings that depend on the installation location of the b4A Service Portal and the b4A RESTful API.

window.env = {
    restApiUrl: '<your REST API url>',
    baseUrl: '',
    title: 'Service Portal',
    logo: '/images/best4automic.svg',
    notification: {
      icon: 'logo512.png'
    },
    language: 'en',
    department: {
        defaultValue: '',
        optional: false
    }
}

Variable	Description	Example
restApiUrl	Contains the complete URL for b4A RESTful API. If the web server is not listening on one of the standard ports, this must also be specified	https://rest.b4a.local/best4automic-api#v2/
baseUrl	Specifies the URL path under which the b4A Service Portal can be accessed on the web server. For a URL https://b4a.local/service-portal, the following value should be specified, which should not end with a slash (/).	/service-portal
title	Specifies the name that is displayed in the web application.	Our own service portal
logo	Specifies the URL path where the logo to be displayed in the web application can be found.	/images/my-logo.svg
notification.icon	Specifies the icon to be used for desktop notifications.	logo512.png
language	The b4A Service Portal is always displayed in one language per installation. The language in which the services provided via the portal are implemented should be selected here. Possible values are de and en	de
department.defaultValue	This value is entered in the login mask as the default value for the department	B4A
department.optional	Boolean value that specifies whether the department is a mandatory field or can be specified optionally	false

The default values for title, logo, and language can be left as they are, as these values are already valid. The same applies to the values below department.

Authorizations

In b4A Service Portal, the available services are divided into categories. These can be assigned to users based on roles. Roles, in turn, are assigned to groups in Automic Automation Engine. These settings are stored in an XML variable. The b4A Package B4A.WEB contains an example of such a configuration variable.

Roles

The roles are defined in the Roles entry. Each role is assigned to a group and each role is assigned a set of categories. The object titles of the groups are displayed for the roles in the b4A Service Portal. It is therefore important that these are maintained and contain meaningful names.

<best4Automic version="5.0.0">
    <web>
        <roles>
            <role name="B4A.WEB.USRG.DEV">
                <category key="DEVELOPMENT"/>
                <category key="TESTING"/>
                <category key="EXAMPLES"/>
            </role>
            <role name="B4A.WEB.USRG.INFO">
                <category key="REPORTING"/>
            </role>
            <role name="B4A.WEB.USRG.BM">
                <category key="PROJECT"/>
                <category key="MARKETING"/>
                <category key="BACK_OFFICE"/>
                <category key="SALES"/>
            </role>
            <role name="B4A.WEB.USRG.ADMIN">
                <category key="DEVELOPMENT"/>
                <category key="TESTING"/>
                <category key="DEPLOYMENT"/>
                <category key="REPORTING"/>
                <category key="ADMIN"/>
            </role>
        </roles>
    </web>
</best4Automic>

The role element introduces a new role definition. The name attribute specifies the group to which the roles are assigned. Any number of categories that are assigned to the role can be referenced in the role definition. A category element is used for each category. The key attribute specifies the key that will later be used to identify the category. The key can be any unique string.

Services

In the second entry, Services, in the XML variable, the services are assigned to the previously defined categories. The category key that was previously defined in the role definition is used for this purpose.

<best4Automic version="5.0.0">
    <web>
        <categories>
            <category key="DEVELOPMENT">
                <label>Development</label>
                <services>
                    <service object="B4A.PM.JOBP.INIT-PACKAGE">
                        <description>
                            Initializes a new b4A Package by creating the basic folder structure in a selected base folder and a set of mandatory objects
                        </description>
                    </service>
                    <service object="B4A.PM.JOBP.BUILD-PACKAGE">
                        <description>
                            Builds a new major, minor or bugfix release of a selected b4A Package. The service includes a dependency and compliance check. If any fails, the build process is canceled.
                        </description>
                    </service>
                    <service object="B4A.PM.JOBP.CHECK-COMPLIANCE">
                        <description>
                            To ensure that all objects of a selected b4A Package follow a set of compliance rules, this service checks the b4A Packages and sends a report to the developer
                        </description>

                    </service>
                </services>
            </category>
            <category key="EXAMPLES">
                <label>Examples</label>
                <services>
                    <service object="B4AE.WEB.JOBP.SMOKE-TEST" taskFilter="none">
                        <description>Check if the configuration is correct and ensure that the communication between Automation Engine, b4A RESTful API and the b4A WebUI works</description>
                    </service>
                    <service object="B4AE.WEB.JOBP.USER-REQUEST-TEST">
                        <description>Starts a service with a request notification object</description>
                    </service>

                    <service object="B4AE.WEB.JOBP.ALL_PARAMS" taskFilter="none">
                        <description>Test Service with all possible parameter types</description>
                    </service>
                    <service object="B4AE.WEB.JOBP.FAILS">
                        <description>Checks if the Service Portal can handle failing services. It should show a notification with activating the service has failed.</description>
                    </service>
                    <service object="B4AE.WEB.JOBP.FAILS" isPassive="true" taskFilter="none">
                        <description>Daily processing of payments</description>
                    </service>
                    <service object="B4AE.WEB.JOBP.MAZE">
                        <description>Just a little maze.</description>
                    </service>
                </services>
            </category>
            <category key="ADMIN">
                <label>Administration</label>
                <services>
                    <service object="B4A.WEB.JOBP.SEND-SERVICE-CONFIG-RELOAD">
                        <description>The b4A RESTful API is requested to reload the service and category configuration</description>
                    </service>
                    <service object="B4A.WEB.JOBP.SEND-SERVICE-CACHE-RESET">
                        <description>The b4A RESTful API is requested to reset all object caches</description>
                    </service>
                </services>
            </category>
            <category key="MARKETING">
                <label>Marketing</label>
                <services>
                    <service object="B4A.DEMO.JOBP.SOCIAL-MEDIA-POSTING">
                        <description>Posts a new statement on LinkedIn, Xing, and BBC Confluence</description>
                    </service>
                </services>
            </category>
            <category key="SALES">
                <label>Sales</label>
                <services>
                    <service object="B4A.DEMO.JOBP.INVITE-TO-TECHTALK">
                        <description>Sends out invitations to the next TechTalk</description>
                    </service>
                </services>
            </category>
        </categories>
    </web>
</best4Automic>

Each category element must contain the key attribute, which contains a category key that was previously used in the role definitions. The text of the label element is used for display in b4A Service Portal. For each service to be displayed in this category, a service element must be created that has an object attribute. The value of this attribute must be the object name of the workflow behind the service. An additional optional attribute is taskFilter, which specifies which executions of a service are displayed in b4A Service Portal. By default, only those executions that do not have a parent, i.e., that were started directly by a user, are displayed. This corresponds to the value no_parent, which does not need to be explicitly specified. However, if you also want to display those executions that were started by a higher-level workflow or scheduler, for example, this must be explicitly specified with none. The optional Boolean attribute isPassive can be used to specify that a service should only appear in monitoring but cannot be started. This can be used to enable users to monitor fully automated processes in b4A Service Portal. Below this element, another element named description must be defined that contains a textual description of the service's function. This text should describe to potential users what function this service performs.

Automation Engine

The permissions described above refer to the view in b4A Service Portal and not to the necessary rights in Automic Automation. The following should be noted in this regard:

To execute services, the user must have the rights to execute the workflow itself.
The user does not need execution rights for services that are configured as “passive.”
All actions in the administration view are performed with the central technical user of the b4A RESTful API. Therefore, the user in the Automic Automation Engine does not need rights to the configuration variable

User settings

Users can make settings in the Service Portal. They are saved by the b4A RESTful API in the Automic Automation Engine in a storage object. A separate file is uploaded here for each user. If there are no user settings for a user yet, the default user settings are loaded, which are also stored in the storage object. The name of the entry - just like the name of the storage object - is configured in the api.json of the b4A RESTful API. The structure of the files is as follows:

{
    "theme": "LIGHT",
    "visibleShortcuts": true
}

theme: Theme for displaying the b4A Service Portal. Possible values are LIGHT and DARK

visibleShortcuts: Display of shortcuts for navigation in the service portal via the keyboard

b4A Packages

One feature of the b4A RESTful API is the ability to send messages to sessions of the b4A Service Portal. This can be achieved via an endpoint in the b4A RESTful API. To make this feature as easy to use as possible, the following b4A Packages are provided:

BBC.SHARED -- Collection of helper functions
B4A.BASE -- Basic integration of the b4A Solution based on actions
B4A.WEB -- Actions for communication with the b4A RESTful API

Such messages consist of a type (information, warning, or error) and a text. HTML elements can be used in the text to display structured information. Links can also be integrated into the messages in this way.

Further detailed information on the individual packages can be found here.

Basic configuration​

Authorizations​

Roles​

Services​

Automation Engine​

User settings​

b4A Packages​