Integrating Third Party System Data Pulls using Service Data Objects and Ebusiness 7 API

Why use the Ebusiness 7 API and web users?

Many integrations involve just pulling data from Aptify to process in a third party system. These types of integrations can be easily setup using a service data object enabled in the Ebiz 7 API, rather than the Aptify Web API. There are numerous benefits to this approach:

1. It is more secure: access to the Aptify Web API by default gives wide access to the service account, as the API is intended for staff-facing purposes. Ebiz 7 was built with security intended for public-facing purposes. This is especially relevant if your Aptify Web is not publicly available
2. It can use web user authentication as opposed to a SQL user or domain user- this is also a more secure approach in general, as a Web User is not going to have the same default access to the database or domain as either a licensed SQL or domain user. This also means your integration users will not take up an Aptify license to run the integration.
3. It can securely support multiple integrations easily- you can easily support multiple integrations using different web user records. You can grant access to specific service data objects to specific web users, so a HighRoads user may have access to different service data objects compared to a HigherLogic user, or a typical website Web User

The EBusiness 7 API* may not be the right answer for all integrations, but it should be the first API-based approach to consider.

Note, this is primarily aimed at use cases involving pulling data from Aptify. It is not recommended to write or update data via SDO to the Aptify database, as that bypasses the GE layer and is not a best practice. Alternatively, you can use a Service Process Flow or new endpoint to update or write data, or you can use the free Aptify marketplace plugin "Generic Entity Update" to write or update data via the GE but using a database object.

(* this approach should work for the Ebusiness 6 API as well. It will not work for Ebusiness Classic)

Setting up Ebusiness 7 API access to Web Users

It's very quick and easy to enable specific Service Data Objects (stored procedures, essentially) to specific web users using the Ebusiness 7 API. This will permit specific web users access to the Service Data Object and endpoint, so all web users will not have access.

To integrate with a third party system, they will first authenticate using the Login WebUser endpoint to obtain a valid token, then use that token calling the newly enabled Service Data Object endpoint to call their specific SDO.

Before enabling the SDO endpoint, you'll need to create a new Web User record for your integration user and assign it to a new Web Users Group named for your integration. Make a note of the Web User Group ID for later.

Step 1: Enabling the SDO endpoint on the E-Business API

To get started, navigate to the Web Services application and select the Service Applications entity. Find your e-Business Service Application record. Click on the Controller Collections tab.

Create a new Controller Configuration Collection record. You can do this easily by adding a new Controller Collection, and then clicking the red hyperlink.

You can name this Controller Configuration Collection record as you would like to indicate this allows the Ebusiness application Service Data Object access via API.

Click the Controller Configurations tab of your new record, and attach the Standard Data Objects record. This is typically ID 11, but it may be different in your system.

Save and close this new Controller Configuration Collections record, and then save and close your Service Applications record. You've now granted the Ebusiness API access to call Service Data Objects although it will not have permission by default to call all of them.

Step 2: Creating or Enabling Your Specific Service Data Object(s) with the Ebusiness API

In the previous step, you enabled the Ebusiness 7 API to call the Service Data Object endpoint. However, by default your service data object will not be enabled in that endpoint. The next step of the process will be to assign Service Data Object(s) to your Ebusiness Service Application. If you would like to grant specific Web Users access to stock Service Data Objects, we recommend cloning them for this purpose as the Aptify Web API will still need access.

Navigate to the Service Data Objects entity within the Web Services application. If you have not already created one for your integration, you can do so here. Find your desired Service Data Object, or create a new one, linking it to the database object to call. You can clone a stock Service Data Object for an example to test with.

Select the Applications tab, and choose your e-Business application. That will grant the e-Business application API access to this specific service data object. It will not have access to all others by default. Save the record.

Step 3: Assigning Security Permissions to the specific Service Data Object

In Step 1, you granted the Ebusiness 7 API access to the Service Data Object endpoint. In Step 2, you enabled specific Service Data Objects within the Ebusiness 7 API access. This step will restrict those Service Data Objects to only specific Web Groups, so all Ebusiness Web Users will not have access to this SDO. 

Go to your Service Data Object.

On the General Tab, check the Enable Security checkbox, then select the Security tab.

Select "Web Groups" for your Authorized Resource Entity, and under Authorized Resource, enter the Web Group ID that you created earlier. Note that you must use an ID here, not the record name. Click OK, and then save your Service Data Object.

This will restrict access to this Service Data Object to Web Users that have been added to that Web Group ID. Other Ebusiness Web Users will not have access to call it.

You're all finished and ready to test this out. Before you can test it, you'll need to reset IIS or the Azure App Service that is running the Ebusiness 7 API layer.

Step 4: Calling your Service Data Object endpoint

You're now ready to call the endpoint. It's recommended to use a tool like Postman to test this out first. Test first with your integration Web User that should have access, and then another Web User that should not to verify setup.

The URL to call for your Ebusiness 7 Web User authentication is going to be  baseURL/services/Authentication/Login/ebusinesswebuser using the GET method. You can then pass the username and password of your integration Web User over as parameters.

This will return a tokenID that you will use to call the specific Service Data Object to return data, passing the TokenID in the header. That URL will be baseURL/services/DataObjects/nameofyourdataobject aalso using the GET method. Make sure to pass in any parameters your SDO / Stored Procedure may need.

You should get the data returned to you correctly. You can now test with a different web user (obtaining a different token first) to confirm the security has been setup properly.

If it does not work, check the error that is returned in Postman or at the IIS / Azure App Service level. Some common troubleshooting steps include:

1. Restarting IIS or the Azure Web App running the Ebusiness 7 API. This is required after all changes to Service Applications and Service Data Objects.
2. Validate the underlying Stored Procedure works properly by querying it directly from SQL Server Management Studio.
3. Ensure all previous steps were completed and saved. You should have
   1. A new controller configure collection with SDO access assigned to the Ebusiness Service application
   2. A service data object assigned to the Ebusiness Service Application, with parameters defined as needed by the Stored Procedure, and security permissions applied to the appropriate Web Group
4. Attempt to call this Service Data Object as a System Administrator to rule out permissions-related issues