Version: Next

RESTful API

The base URI for each request has the form http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api when the name of the delivered WAR archive is used. In the case of the standalone variant, the default base URL is http[s]://{host}:{port}. The following examples always show the first variant. The OpenAPI specification contained therein can be accessed by extending the base URL with /swagger-ui.html. All endpoints, including parameterization and return values, are described here.

When starting the b4A RESTful API, a valid license for b4A must be in the configuration directory.

The b4A RESTful API works with UTF-8 for all input and output files.

Authentication

Depending on configuration, authentication is carried out with a user name and password (basic authentication) or with a JWT token.

Basic authentication

If basic authentication is activated, the user name and password must be entered in the Authorization header for every request against the b4A RESTful API. The user name must be specified with USERNAME/DEPARTMENT. The entire service area of the b4A RESTful API is not available here, regardless of the user's roles. The Authorization header must be specified as usual for Basic authentication with <USERNAME>:<PASSWORD> in Base64 encoding. Example

Authorization: Basic REVNTy9CNEE6RHVEZWNvZGVzdEFsc29VbnNlclBhc3N3b3J0LlNvU28h

Token-based authentication

With this authentication method, the full range of functions of the b4A RESTful API is generally available. Which requests a user is allowed to execute depends on their assigned roles. A JWT token must be included with each request. There are two options for doing this: transfer via the Authorization header or via an HttpOnly cookie. Both options are described below.

Bearer token in the Authorization header

This method is recommended for manual, technical, and automated calls to the b4A RESTful API. To generate a token, the following login endpoint must first be called via a POST request.

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/login

The login data is transferred in the body of the request:

{
  "username": "DEMO/B4A",
  "password": "<Passwort>",
  "language": "de"
}

An example response looks like this:

{
  "user": {
    "username": "DEMO/B4A",
    "firstName": "Demo",
    "lastName": "b4A"
  },
  "emailAddress": "demo@b4A.de",
  "expires": "2022-08-05T12:00:00.000Z",
  "roles": [
    {
      "name": "B4A.ROLE.1",
      "title": "First role"
    },
    {
      "name": "B4A.ROLE.2",
      "title": "Second role"
    }
  ],
  "restRoles": [
    "ADMIN",
    "SERVICE",
    "MODULE"
  ]
}

The JWT token itself is not returned in the body of the response, but is located in the header under the key Authorization. The body indicates when the token expires. The validity period of the token is configurable. In addition, the so-called secret (secret key) and the issuer (issuer of the token) can be configured, on the basis of which the token is generated (see Details). After restarting the b4A RESTful API, all previously issued tokens lose their validity.

All further requests must include the generated token in the Authorization header. This looks like the following, for example:

Authorization: Bearer eyJhbGciOiJIUzUxGjkiJ9.nOIHfIjoiZGUuYmVzdGJsdS5yZXN0YXBpIiwiaWF0IjoxNjQzMDA4Njc1LCJleHAiOjE2NDMwMzc0NzV9. xYGmrfMidALVySU6yfoO4sNWbdl4LSIpcbDJTdgiIc0O4cAHxp6UP9KXlF_wh1fmEGcK3WY_b5

This method is recommended for secure communication between the browser and b4A RESTful API. In particular, b4A Service Portal uses this variant of token-based authentication. If SAML is not used, access is via the following endpoint (POST request):

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/auth/login

The request and response are basically the same as for the /login request. However, the backend also generates an HttpOnly cookie named JWT, which is stored in the browser. This cookie is automatically sent by the browser with every subsequent request.

HttpOnly cookies are also used when SAML is used. In this case, authentication is initiated via the Assertion Consumer Service URL. For more information, see the chapter SAML.

note

When using unencrypted connections (HTTP instead of HTTPS), modern browsers enforce strict security policies regarding cookies. Therefore, the following is mandatory for the setup: The b4A Service Portal and b4A RESTful API must communicate using exactly the same hostname or IP address. If these do not match, the browser will block the authentication cookies.

Logout

Since a connection to Automic Automation Engine is established with each login, each session should be terminated properly. The following logout endpoint (POST request) is available for this purpose. A request body is not required.

http[s]://{host}:{port}/best4automic-rest-v4/api/logout

roles

Authorization is managed in the b4A RESTful API via four roles. The roles are mapped via user groups in the Automic Automation Engine. The names of the user groups in the Automic Automation Engine can be configured (Details).

Role	Configuration	Description
Info	rest.auth.groups.info	A user with this role only has "read" access to the b4A RESTful API. Only the license, connection and version endpoints as well as GET requests to the module endpoint are permitted.
modules	rest.auth.groups.module	Users in this group have the authorization to execute modules in addition to the info authorizations.
Service	rest.auth.groups.service	This authorization is required if the service area of the b4A RESTful API is to be used in addition to the module authorizations. Excluded are administrative endpoints and the endpoint for messages from the Automic Automation Engine.
Admin	rest.auth.groups.admin	In addition to the authorizations of the service role, the group of admins may also operate the administrative endpoints and perform clean-up work using the DELETE requests of the module endpoint and file endpoint. The only endpoint that is even denied to the admin user is the already mentioned endpoint for messages.

Messages from the Automation Engine

The post request for sending messages from the Automic Automation Engine has a special role in the b4A RESTful API. It is intended exclusively for sending messages from the Automic Automation Engine to the b4A Service Portal. An installation-specific token is required to be able to use this endpoint. This can be configured (Details on the key rest.auth.status.token). The b4A Package B4A.WEB provides an action that can be used to send messages to the b4A Service Portal. More information about this b4A Package can be found at https://docs.best4automic.de/packages. For further information on the b4A Service Portal, please refer to its documentation. Messages that are sent to the b4A RESTful API via this action are distributed via Websockets to all users authorized for the respective service and logged in to the b4A Service Portal.

Websockets

The b4A RESTful API generates messages in some places that are distributed via websockets. A websocket to the b4A RESTful API is opened against the following URL.

http[s]://{host}:{port}/best4automic-rest-v4/api/service/event

Communication via the web socket is based on the STOMP protocol. The b4A Service Portal registers for topics for which it would like to receive messages. All topics that can be subscribed to are listed and described below.

Topic	Description
/user/queue/service/status/changed	If the status of a service has changed, a message is sent to all users with an open web socket who are authorized for the specific service.
/user/queue/service/notification/changed	When a notification object is executed for which the user is registered as the recipient, a corresponding message is sent via the web socket. The message contains the RunId for the execution of the notification object. To receive the message, the user must have sent the GET request /service/notifications to the b4A RESTful API at least once before. Otherwise, the user will not be notified of these changes.
/user/queue/service/notification/action	If a notification object for which the user is entered as the recipient has been answered by someone other than themselves via the POST request /service/notification/{runId}, the user receives a corresponding message.
user/queue/service/notification/comment/added	If a comment has been added to a notification object via the POST request /service/notification/{runId}/comment, the user will receive a corresponding message.
/user/queue/service/message/added	The messages are forwarded via this.
/user/queue/service/start/initiated	If a service was successfully started via the POST request /service, a message is sent via this topic to all users who are authorized for the specific service.
/user/queue/service/start/failed	If the start of a service via the POST request /service was not successful, a message is sent via this topic to the user who tried to start the service.
/user/queue/service/start/external/detected	If a service that has none as TaskFilter or has been marked as passive was started outside the b4A Service Portal (e.g. directly in the AWI, via Scheduler, Automic REST-API, Call-API...), a message is sent via this topic to all users who are authorized for the specific service. Services marked as private are not recognized by this mechanism.
/user/queue/service/config/changed	If the configuration was reloaded via the PUT request /service/admin/config/reload, all users are informed of this.
/user/queue/service/input/required	If a PromptSet is available for a user to enter, which belongs to a service or one of its subtasks, the user is informed of this via this topic. Using the RunId received, the GET request /service/{runId}/parameter/list can then be used to query the parameters to be filled in.
user/queue/service/input/cancelled	If a task that contained an open PromptSet was terminated via the endpoint /service/cancel/{runId}, the user is informed about the termination of the task via this topic.
user/queue/service/history/{id}	If historical data was requested from services via the /service/history endpoint, the user receives a topic in the response, which they must then subscribe to. The response with the historical data is then sent via this topic.

Example requests

A description of all endpoints with schema and examples can be found in the OpenAPI specification, to which reference was made at the beginning. Nevertheless, some examples are documented here.

License

To check whether the RESTful API has been installed and configured correctly, the license endpoint can be called (GET request).

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/license

If the request was successful, the purchased license should be returned. The response should look like this, for example.

{
  "license": {
    "company": "best-blu consulting with energy GmbH",
    "type": "Production",
    "bundle": "All-in-One",
    "categories": [
      "te",
      "ana",
      "mc",
      "info",
      "util",
      "tp",
      "pm",
      "ta",
      "vcs",
      "service-portal"
    ]
  },
  "valid": true,
  "message": ""
}

Modules

Execute module

To execute a module, a POST request must be sent to the following endpoint.

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/module

A body must be sent with this request. This must have the following format.

{
  "name": "info.search",
  "options": {
    "connection": "AE21PROD-1000",
    "save-objects": "search-results.txt",
    "name": "*BEST*"
  }
}

If successful, it returns the HTTP status 202 Accepted in response. As is usual for REST APIs, there is no waiting for the end of execution. If required, a callback mechanism can be used to be informed about the end of the module execution. To do this, the request body must be extended to include the callback information.

{
  "name": "info.search",
  "options": {
    "connection": "AE21PROD-1000",
    "save-objects": "search-results.txt",
    "name": "*BEST*"
  },
  "callback": {
    "url": "http://callback/url/endpoint"
  }
}

If only the callback URL is specified, a POST request is sent to the specified URL. The Content-Type is set to application/json as the standard header and the following content is sent as the standard request body:

{
  "runId": 1,
  "status": "COMPLETED",
  "errorMessage": "",
  "returnCode": 0
}

Alternatively, you can send a PUT request. The request type type must then be specified. Of course, the default value POST can also be specified here. The headers can also be overwritten. The request body for the callback can also be assembled using b4A Expressions. Here is a complete example:

{
  "name": "info.search",
  "options": {
    "connection": "AE21PROD-1000",
    "save-objects": "search-results.txt",
    "name": "*BEST*"
  },
  "callback": {
    "url": "http://callback/url/endpoint",
    "type": "POST",
    "headers": {
      "Authorization": "Basic WW91RGVjb2RlZE1lPyE=",
      "Content-Type": "application/json"
    },
    "bodyFormat": "{\"execution_option\": \"execute\",\"object_name\": \"SCRI.CALLBACK\", \"inputs\":{\"RUN_ID_I#\": \"%(run_id)\", \"MODULE_STATUS_I#\": \"%(module_status)\", \"ERROR_MESSAGE_I#\": \"%(error_message)\", \"RETURN_CODE_I#\": \"%(return_code)\"}}"
  }
}

The execution status can be queried with another request. First, the example response for a POST request.

{
  "id": 1,
  "updated": "2021-06-28T13:39:06.705+00:00",
  "name": "info.search",
  "status": "INITIATED",
  "returnCode": 0,
  "errorMessage": "",
  "options": {
    "log-flags": [
      "MONOCHROME",
      "TIMESTAMP"
    ],
    "log-variants": [
      "REPORT"
    ],
    "log-datastream-separator": "§§",
    "log-datastream-prefix": "@B4A_STREAM@",
    "recursive": true,
    "folder-ignore-missing": false,
    "log-levels": [
      "ERROR",
      "WARNING",
      "INFO"
    ],
    "parse-processes": false,
    "encryption-key": "server",
    "save-success-only": true,
    "connection": "AE21PROD-1000",
    "end": "2021-06-28 15:39:06",
    "test-mode": false,
    "exclude-list": "/var/lib/tomcat9/webapps/best4automic-rest-v4#api/data/3/exclude-list",
    "search-date": "none",
    "log-error-mode": "never",
    "search-in-vara-type": "text",
    "types": [
      "CALE",
      "CALL",
      "CITC",
      "CLNT",
      "CODE",
      "CONN",
      "CPIT",
      "DASH",
      "DOCU",
      "EVNT",
      "FILTER",
      "FOLD",
      "HOST",
      "HOSTG",
      "HSTA",
      "JOBF",
      "JOBG",
      "JOBI",
      "JOBS",
      "JOBP",
      "JOBQ",
      "LINK",
      "LOGIN",
      "JSCH",
      "SCRI",
      "SYNC",
      "TZ",
      "USER",
      "USRG",
      "VARA",
      "XSL",
      "PRPT",
      "QUEUE",
      "STORE",
      "SLO",
      "PERIOD"
    ],
    "exclude-ignore": false,
    "save-append": false,
    "input-mode": "search",
    "include-links": false,
    "datastream-object-type": false,
    "save-objects": "/var/lib/tomcat9/webapps/best4automic-rest-v4#api/data/3/search-results.txt",
    "traverse-flows": false,
    "name": "*BEST*",
    "begin": "2021-05-28 15:39:06"
  },
  "_left": {
    "get_module": {
      "href": "http[s]://{host}:{port}/best4automic-rest-v4/api/module/1"
    },
    "get_report": {
      "href": "http[s]://{host}:{port}/best4automic-rest-v4/api/module/1/report"
    },
    "get_output": {
      "href": "http[s]://{host}:{port}/best4automic-rest-v4/api/module/1/output/save-objects"
    }
  }
}

Useful follow-up requests are listed in the lower section of the response. In this case, the first request can be used to query the status and further information about the running of the module. The second can be used to retrieve the report and the third to retrieve the output file of the save-objects option.

If an option requires an input file, the file can be transferred in three different ways.

The first option is to transfer the file content as a Base64-encoded character string.

{
  "name": "Search",
  "options": {
    "connection": "AE21PROD-1000",
    "input-mode": "file",
    "input": "Sk9CUzpCNEEuQkFTRS4qCkZPTERFUjpQQUNLQUdFUy9CRVNULUJMVS9CQkMuU0hBUkVE"
  }
}

Alternatively, a file can be transferred in the file URI scheme. For example, a file that was previously uploaded using the "/file/upload" endpoint can be transferred here.

{
  "name": "Search",
  "options": {
    "connection": "AE21PROD-1000",
    "input-mode": "file",
    "input": "file:///var/lib/tomcat9/webapps/best4automic-rest-v4#api/data/uploadDir/b4A.9452653586426052242.input.txt"
  }
}

The last option applies explicitly to CSV input files. These can also be transferred as a list of lists of character strings.

{
  "name": "Search",
  "options": {
    "connection": "AE21PROD-1000",
    "input-mode": "file",
    "input": [
      [
        "JOBS:B4A.JOBS.NEW.1",
        "B4A.TESTS/SAMPLES"
      ],
      [
        "JOBS:B4A.JOBS.NEW.2",
        "B4A.TESTS/SAMPLES2"
      ]
    ]
  }
}

Further requests for this run

The GET requests are to be sent as they were sent in the answer above.

This request is sent for information about the options, the status or any error messages.

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/module/1

The response is very similar to the POST request. In this case, however, the module has already run successfully.

{
  "id": 1,
  "updated": "2021-06-28T12:17:40.999+00:00",
  "name": "info.search",
  "status": "COMPLETED",
  "returnCode": 0,
  "errorMessage": "",
  "options": {
    "all": "options",
    "for": "this",
    "run": "!"
  },
  "_left": {
    "get_report": {
      "href": "http://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/module/1/report"
    },
    "delete_module": {
      "href": "http://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/module/cleanup/1"
    }
  }
}

The statuses can be

INITIATED: Run has been initialized
IN_PROGRESS: The module has been started but not yet completed
COMPLETED: The module has been successfully completed FAILED: The module was terminated with errors. In this case, further information can be found in the returnCode and the errorMessage.

The following request must be sent for the run report.

http://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/module/1/report

The output file of the save-objects option is queried in a similar way.

http://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/module/1/output/save-objects

Depending on the file extension specified in the post request, the media type of the file is guessed and set in the header of the response.

Service

List of services

This GET request returns the list of services for a specific category. Example:

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/service/list/EXAMPLES

{
  "category": "EXAMPLES",
  "services": [
    {
      "name": "B4AE.WEB.JOBP.SMOKE-TEST",
      "title": "Smoke Test",
      "description": "Check if the configuration is correct and ensure that the communication between Automation Engine, b4A RESTful API and the b4A WebUI works",
      "exists": true,
      "isPassive": false,
      "hasPrompt": true
    },
    

    
  ]
}

If the passive services are also to be returned, the request parameter includePassive can be used, which is false by default and must be set to true for this purpose.

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/service/list/EXAMPLES?includePassive=true

List of active instances of services

To obtain the active instances of all services in the category, the following GET request must be sent. By default, only those instances are returned here that have no parent, i.e. were started directly by a user. If instances that were started by a scheduler, for example, are also to be returned, this must be configured for each service. Further information on this can be found in the b4A Service Portal documentation

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/service/tasks/EXAMPLES

{
  "category": "EXAMPLES",
  "services": [
    {
      "name": "B4AE.WEB.JOBP.ALL_PARAMS",
      "title": "Test with different parameters",
      "instances": [
        {
          "user": {
            "username": "DEMO/B4A",
            "firstName": "Demo",
            "lastName": "best4Automic"
          },
          "runId": 2747459,
          "completedTasks": 14,
          "numberOfTasks": 16,
          "waitingForApproval": false,
          "waitingForInput": false,
          "status": null,
          "statusCode": 1550,
          "statusText": "Active",
          "messages": [
            {
              "message": " Thanks for using b4A Web UI :-)\r\n",
              "type": "INFO"
            },
            {
              "message": " This is quite a long message which is used to show you what happens with such log text segments in the b4A Service Portal. Beautiful, right?\r\n",
              "type": "INFO"
            },
            {
              "message": " This is quite a long message which is used to show you what happens with such long text fragment in the b4A Service Portal. Beautiful, right?\r\n",
              "type": "INFO"
            },
            {
              "message": " First task of service has been finished\r\n",
              "type": "INFO"
            },
            {
              "message": " Second task of service is going to start\r\n",
              "type": "INFO"
            },
            {
              "message": " Second task of service has been finished\r\n",
              "type": "INFO"
            }
          ],
          "parameters": [
            {
              "variable": "NUMBER1#",
              "type": "Number",
              "options": {},
              "label": "Number",
              "value": "0"
            },
            {
              "variable": "TEXT1#",
              "type": "TextView",
              "options": {},
              "label": "Text Field (Multiline)",
              "value": "Default Value\nDEMO/B4A\nDemo best4Automic\ndevelopers@best4automic.de"
            },
            {
              "variable": "TEXT2#",
              "type": "TextView",
              "options": {},
              "label": "Text Field",
              "value": "23092024 --- 140030"
            },
            {
              "variable": "TEXT3#",
              "type": "TextView",
              "options": {},
              "label": "Text Field",
              "value": ""
            },
            {
              "variable": "TEXT4#",
              "type": "TextView",
              "options": {},
              "label": "Text Field",
              "value": ""
            },
            {
              "variable": "TEXT5#",
              "type": "TextView",
              "options": {},
              "label": "Text Field",
              "value": ""
            },
            {
              "variable": "CHECKBOX1#",
              "type": "CheckBox",
              "options": {
                "array": true,
                "separator": ";"
              },
              "label": "Checkbox, array",
              "value": [
                {
                  "value": "value3",
                  "label": "value3"
                },
                {
                  "value": "value1",
                  "label": "value1"
                }
              ]
            },
            {
              "variable": "CHECKBOX2#",
              "type": "CheckBox",
              "options": {
                "array": false,
                "separator": ";"
              },
              "label": "Checkbox",
              "value": [
                {
                  "value": "value2",
                  "label": "value2"
                },
                {
                  "value": "value1",
                  "label": "value1"
                }
              ]
            },
            {
              "variable": "COMBOBOX1#",
              "type": "ComboBox",
              "options": {},
              "label": "Combobox",
              "value": {
                "value": "value1",
                "label": "value1"
              }
            },
            {
              "variable": "COMBOBOX2#",
              "type": "ComboBox",
              "options": {},
              "label": "Combobox, read-only",
              "value": {
                "value": "REPORT",
                "label": "REPORT"
              }
            },
            {
              "variable": "DATETIME1#",
              "type": "Date",
              "options": {},
              "label": "Time/Date",
              "value": "2024-09-23"
            },
            {
              "variable": "DATETIME2#",
              "type": "Timestamp",
              "options": {},
              "label": "Time/Date",
              "value": "2024-09-26 06:30:00"
            },
            {
              "variable": "DATETIME3#",
              "type": "Time",
              "options": {},
              "label": "Time/Date",
              "value": "11:30"
            },
            {
              "variable": "RADIOGROUP1#",
              "type": "RadioGroup",
              "options": {},
              "label": "Radio Button",
              "value": {
                "value": "value2",
                "label": "value2"
              }
            }
          ],
          "startTime": "2024-09-25 13:37:20"
        },
        

        
      ]
    },
    

    
  ]
}

This example response shows how the b4A RESTful API works with parameter values. A character string is always returned for text fields, number fields, date fields and time fields. For radio buttons and combo boxes, a JSON object with a value value and a label label is always returned. For checkboxes, a list of these JSON objects is always returned. This applies to all requests and web socket messages in the b4A RESTful API. The parameters must also be provided accordingly for requests, for example when starting a service with parameters. For various requests to query possible parameter values, a list of the JSON objects described above is always used. As different object types are possible here, this cannot be shown directly in the Swagger documentation.

List of historical instances of services

A POST request is made to retrieve historical instances of services.

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/service/history

A list of services and a time period for the activation date must be specified here. A list of users can also be optionally specified. If none is specified, the versions of all users are queried. The body of the request looks like this, for example.

{
  "services": [
    "B4AE.WEB.JOBP.SMOKE-TEST",
    "B4AE.WEB.JOBP.ALL_PARAMS"
  ],
  "users": [
    "DEMO/B4A"
  ]
  "activationTime": {
    "begin": "2023-07-22 00:00:01",
    "end": "2024-07-25 19:55:47"
  }
}

The topic to be subscribed to is sent as the response, as the response is sent asynchronously via the web socket.

{
  "topic": "/user/queue/service/history/6f667f7e-262d-4e3f-b083-898e51f637ed"
}

Starting a service

A POST request is required to start a service. The workflows behind the services must be generated at runtime if PromptSets are attached directly to the workflows.

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/service

The body of the request looks like this, for example.

{
  "name": "B4AE.WEB.JOBP.SMOKE-TEST",
  "category": "EXAMPLES",
  "parameters": {
    "B4AW_TEST_I#": "Demo"
  }
}

The RunId of the started service is returned as the response.

{
  "runId": 1919242
}

When passing the parameters, you can work with the familiar syntax from Automic Automation Engine to access the contents of VARA objects (curly brackets). Some system variables are also available. These are listed below:

&$SYSTEM#
&$CLIENT#
&$CLIENT_DESC#
&$DEPARTMENT#
&$USER#
&$ACTIVATOR#
&$USER_FL#
Date specifications with &$DATE_format#, &$LDATE_format# and &$PHYS_DATE_format#. In the b4A RESTful API they are all treated like &$PHYS_DATE_format#. The time zone with which the JVM is running is used.
Time specifications with &$PHYS_TIME_format# , &$TIME_format#
&$B4A_USER_EMAIL#: E-mail address of the user.

The last variable is only resolved if the service is started via the b4A RESTful API. It is not resolved in the Automic Automation Engine.

The endpoint preallocates the PromptSet fields according to the parameters provided. However, the parameters do not necessarily have to be sent. In this case, the service is activated but, if it has a PromptSet, waits for the PromptSet to be sent. In this case, the user receives a message via the web socket that a PromptSet is ready for input. In this case, services in which the underlying workflow is generated at activation time play a special role. In this case, the b4A RESTful API would only learn of the successful activation of the service once the PromptSet has been sent. As a result, this endpoint runs into a timeout. If a service is to be started without parameters, even though it contains a PromptSet, this must be set to generation at runtime. The b4A Service Portal always sends the parameters at startup. This case can therefore be ignored. The b4A Service Portal can therefore also handle the services if they are generated at activation time and have a PromptSet.

Upload files

Files can be uploaded to the defined upload directory using the following endpoint:

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/file/upload

The file must be attached to the request as multipart/form-data. The file is created in the target directory with the prefix b4A.<randomNumber>. The response includes the file URI of the uploaded file.

{
  "fileName": "b4A.11437492026587812739.hello_world.txt",
  "uri": "file:///var/lib/tomcat9/webapps/best4automic-rest-v4#api/data/uploadDir/b4A.9452653586426052242.input.txt",
  "fileType": "text/plain",
  "size": 12
}

Search services and categories

The following endpoint can be used to search the services and categories available to the user. A POST request is required. The search takes the user's permissions (UserGroups) into account and filters the results accordingly.

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/service/search

The body of the request contains the search term:

{
  "searchTerm": "Smoke Test"
}

The response is an object containing two lists:

services: A flat list of all services found.
categories: A hierarchical view in which the services found are assigned to their categories.

{
    "services": [
        {
            "name": "B4AE.WEB.JOBP.SMOKE-TEST",
            "title": "Smoke Test",
            "description": "Check if the configuration is correct and ensure that the communication between Automation Engine, b4A RESTful API and the b4A WebUI works",
            "exists": true,
            "findings": [
                "title"
            ],
            "isAuthorized": true,
            "isExecutable": true,
            "isPassive": false,
            "isPrivate": false
        }
    ],
    "categories": [
        {
            "key": "EXAMPLES",
            "label": "Examples",
            "services": [
                {
                    "name": "B4AE.WEB.JOBP.SMOKE-TEST",
                    "title": "Smoke Test",
                    "description": "Check if the configuration is correct and ensure that the communication between Automation Engine, b4A RESTful API and the b4A WebUI works",
                    "exists": true,
                    "findings": [
                        "title"
                    ],
                    "isAuthorized": true,
                    "isExecutable": true,
                    "isPassive": false,
                    "isPrivate": false
                }
            ],
            "findings": [],
            "isAuthorized": false
        }
    ]
}

By default, the search is performed using the title and description of the services as well as the key and label of the categories. Whether the technical object name (e.g., B4AE.WEB.JOBP...) is also searched for depends on the user settings in the Service Portal.

The following rules apply to the search results:

Visibility & permissions: A distinction is made between regular users and administrators:
- Regular users: Only receive services and categories for which their user group is authorized. In addition, the services must be technically startable (i.e., active, existing, and executable).
- Administrators: Receive an unfiltered view for error analysis. They also see services and categories for which they do not have authorization. Services that are passive, non-existent, or non-executable are also displayed.
Category view: If a search hit is only found in the description (marked as description in findings), but not in the name or title, the service appears in the flat services list, but is not sorted into the categories structure.

Maintenance and administration

The b4A RESTful API involves certain administrative tasks. The module execution generates output files and entries in the database. These should be cleaned up regularly. The b4A RESTful API offers two DELETE endpoints for this purpose. With the first option, all data for a specific run can be deleted using the ID.

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/module/{id}

The second DELETE endpoint deletes all data that is older than a selected number of days.

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/module/cleanup

This request must be accompanied by a body that defines how many days of execution information should be retained.

{
  "numberOfDaysToKeep": 7
}

An endpoint is available in the file area to clean up the upload directory.

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/file/cleanup

As with the previously mentioned housekeeping endpoint for modules, the number of days for which files are to be kept must be specified.

There are two endpoints for the service area that support administration. Services are already supplied for these in the B4A.WEB package. They can therefore be called directly from the b4A Service Portal. The b4A RESTful API has several caches so that the Automic Automation Engine is not confronted with too many requests. Firstly, the XML configuration of the services and roles is cached. If there are changes to this, the following PUT request must be called.

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/service/admin/config/reload

In addition, objects are cached so that they are not constantly queried from the Automic Automation Engine. In some cases, this requires these caches to be reset:

Changes to the PromptSets of an existing service
Changing the title of an existing service
Changes to the authorizations of a user who has already tried to authenticate against the b4A RESTful API

This is done with the following PUT request.

http[s]://{host}:{port}/best4automic-rest-{b4A Core Version}-v4/api/service/admin/cache/reset

Authentication​

Basic authentication​

Token-based authentication​

Bearer token in the Authorization header​

HttpOnly Cookie​

Logout​

roles​

Messages from the Automation Engine​

Websockets​

Example requests​

License​

Modules​

Execute module​

Further requests for this run​

Service​

Categories​

List of services​

List of active instances of services​

List of historical instances of services​

Starting a service​

Upload files​

Search services and categories​

Maintenance and administration​