Skip to main content
Version: 2.2.1

General questions

General questions​

Integration of portals and/or legacy systems for starting workflows within SoftExpert Suite.​

  • The integration can be performed using SoftExpert Suite web services. SoftExpert Suite web services are detailed in the "Integration via web services" chapter.
info
Note:

Other actions within the Workflow component are also possible through SOAP web services, such as activity execution, attribute input, form field completion, attachment upload, etc. (online documentation on web services: https://<domain>/se/ws/wf_ws.php).

Using Dataviz tools for SoftExpert Suite source view.​

  • For this purpose, we recommend using the dataset API that allows assembling the intended queries. The data dictionary of our product is available online in the SoftExpert Configuration component > Tool > SQL editor > "Documentation" button.

Integration of customers' external systems for creating and adding various pieces of data in SoftExpert Suite.​

  • For this type of demand, we provide interface templates and the web services or APIs themselves; they are all detailed in "Reference".

Reading external database data to use them within SoftExpert Suite.​

  • For this purpose, we have the external attributes feature within the application. Details on how to configure external attributes can be found in the SoftExpert Administration manual.
  • And, regarding the components based on SoftExpert Process, we have the option of configuring external applications, through which it is possible to test external information, return any type of data, etc., either using the Web Service, API concept, or even a customized application (by means of customization).
info
Note

The same concept may be applied for loading form field list data. In that case, there is no option for direct connection to the external attribute; the dataset can be used.

Saving information in external systems through SoftExpert Suite.​

  • To do so, you can use web services or APIs (if the external system has any), export to data files (TXT, CSV), for import through the external system, or save the data directly into the database of the external system.
  • And, regarding the components based on SoftExpert Process, we have the option of configuring external applications, through which it is possible to configure web service clients natively (except for authentication and architecture singularities, for which case the specific client would have to be implemented).

Integration when hosting.​

  • Restrictions depend exclusively on the infrastructure available for the tools that will be used. For example, if there is a direct connection between the databases, they must enable a DBLINK or be on the same network (dedicated VPN). If file transfer is needed, the file servers must be available in the cloud, and so on.
  • The architecture suggested for these cases is the use of APIs or web services.

Possible integrations with SAP ERP.​

  • These integrations can be performed by any SAP tooling (ABAP, XI, RFC, etc.); they are more dependent on the contract the customer has. However, routine implementations directly in SAP are usually carried out by the customer's IT team or SAP consultants.
info

The same reasoning can be applied to any other ERP, that is, the SoftExpert team needs to map the data provision method that will be used by the ERP. The aforementioned methods are defined based on that.

General questions about using integrations​

What type of license is more adequate for API calls?​

License types vary according to what is needed. For example, if someone with a STAFF license is a web service user, they will not be able to create new users through the adm_ws service, since this is a feature that requires a more permissive license.

Can I consume an API with a logged user?​

Yes, as long as the license allows it.

What is the actual difference between a "regular" and an "API" user session?​

The main difference between a "regular" and an "API" user session lies on the way both consume licenses and manage their sessions. In both cases, a license is consumed. However, when a web service is called, it does not register your session in the session table. This means that access through /apigateway does not conflict with other web service or API calls for the same user, since none of them will register an active session.

However, a scenario to be considered is when there is only one license for simultaneous users and there already is a user logged in to SoftExpert Suite – viewing a portal, for example. In this situation, web service calls will return an error 403. This happens because there is a user already consuming the only session actually available.

Therefore, while the "regular" and "API" user sessions may look similar at first, they have different characteristics as to license and session management, which must be taken into account in the design and implementation of solutions that use these resources.

Considering these scenarios, what is suggested?

  1. Register a specific user for API and SOAP web service consumption.
  2. Leave only one license available for this user. This is necessary because, in the case of external calls (whose license is not provided), SoftExpert Suite will use the first license it finds.
  3. Use a permissive license, according to your needs (if you wish to start workflows via web service, the license type must support this feature).

About request logs sent to SoftExpert, are they stored in it?​

Request logs sent to SoftExpert Suite are stored in the system itself. They can be accessed through the widgets available in the elements of the SoftExpert Administration component, which can be used during the creation of a portal. Alternatively, these logs can also be viewed through the import of a customized system portal.

This way, both the administrators and the users will be able to monitor and analyze requests sent to SoftExpert Suite, which makes it easier to track activities and solve potential problems.

What do I need to know about API error messages?​

Unless stated otherwise, most SoftExpert Suite endpoints returns a 200 OK response to indicate a successful operation. If an API or web service returns a different status code, specific information about the response will be detailed in its own documentation.

SoftExpert Suite also has several standard error responses that different APIs share:

  • 401 Unauthorized: Response returned when the provided authentication is invalid. For details on how to correctly authenticate API requests, refer to our authentication and security section.
  • 403 Forbidden: Code returned when the provided authentication does not contain the required permissions to access the specific URL.
  • 429 Too Many Requests: Response returned when your account or application exceeds the API rate limits. We offer suggestions on how to operate within those limits in our documentation.

Why am I receiving a Valid GatewayJWT not found in the request or user is blocked! message?​

This message is usually displayed when an error 401 occurs. In most cases, this means that the API key required for authenticating the request has not been added to its header. Making sure that the API key is correctly incorporated into the header of all requests you send is imperative for this error to be prevented.

Alternatively, this message may also appear if the user used for the integration is blocked. If that is the case, check the status of the user and take the necessary measures to unblock them.

If you continue to receive this message after performing these two verifications, we suggest you contact the technical support for further assistance.

Is it possible to use Bearer Tokens in our REST data source definitions? If it is, how can we set it up?​

Currently, the Bearer Token authentication option is not available among the authentication types supported by the REST data source (AD052) menu. However, you can work around this limitation by adding a custom header to meet this requirement on the input parameters configuration screen and selecting the parameter type as HEADER. To perform this configuration, create the header as follows:

Bearer <Your API key>

If the token is dynamic, you will need to use the resources of the BPM components in order to pass the token on to this parameter dynamically. For more detailed information, we recommend that you contact your account executive for personalized consulting.

To learn how to configure a REST data source, go to Configuring a REST data source.

Dataset API​

Can I use the dataset API in the Power BI Online service?​

Yes, you can use the SoftExpert Suite dataset API as a data source in Power BI Online. However, it is important to remember that, for customers that have SoftExpert Suite on-premise environments and are on private networks, access to the Power BI Online service must be ensured for proper functioning. In these cases, we recommend you consult your Infrastructure team responsible for supporting SoftExpert Suite or the Power BI documentation itself.

Is it possible to set up pagination in the dataset API?​

At the moment, the dataset API does not support pagination. This means that only the first 10,000 (ten thousand) records can be obtained as objects. If a customer needs to retrieve more records, they will need to create a logic in their SQL script in order to get the total number of records returned on the dataset view or creation screen.

info
Note:

Not all APIs support pagination. When that happens, it may be necessary to create alternative logics on the customer's side for the manipulation of large datasets, such as splitting the query into smaller pieces or getting the total number of records in order to allow the results to be displayed in stages.

Dataset interface​

How can I solve error 404 “NoSuchKey” in the error description on the Configuration > Tool > Import: Tracking (CM015) screen?​

If you have encountered error 404 "NoSuchKey" during a data import, do not worry – there is a solution. This error indicates that the requested object has not been found in the SFTP (S3 bucket) during the import process.

What does this mean? The "NoSuchKey" error occurs when the system cannot find the object required for data import. This can happen for various reasons, including configuration problems or missing files.

How to solve it: Follow these steps to fix the issue:

  1. Verify the presence of the electronic file: Make sure the required electronic file was created and is available in the SFTP provided by SoftExpert.
  2. Confirm the correct SFTP: Check that the electronic files are in the right SFTP for each contracted environment. Each environment has its own SFTP.
  3. Fix the reference to the electronic file: Make sure the reference to the electronic file is correct in the data import configuration of the template being used.

If you need further guidance, we recommend reading our document with guidelines on the use of file storage for integration (Amazon S3).

Need additional help? If the problem persists, or if you have questions, contact our technical support team for additional assistance.

Technical description of the error:

{
  "error": "Internal Server Error",
  "exception": "com.amazonaws.services.s3.model.AmazonS3Exception",
  "message": "The specified key does not exist. (Service: Amazon S3; Status Code: 404; Error Code: NoSuchKey; Request ID: <Request ID>; S3 Extended Request ID: <S3 Extended Request ID>)",
  "status": 500,
  "time": 1707745683813
}