Global Mailbox REST Services

The Global Mailbox implementation supports REST services to view and consume some resources in the Sterling B2B Integrator and Sterling File Gateway.

The REST services are hosted in an instance of HTTP Server adapter, which is named, Global Mailbox REST Services adapter. The Global Mailbox REST Services adapter is preconfigured (by default) on a dedicated port and uses basic authentication (over SSL) to confirm that only users with appropriate permissions are allowed to access the resources on Sterling B2B Integrator. By default, a user who is named, gmbx_user is shipped with permissions (Global Mailbox User Lookup REST API and Global Mailbox Event Property REST API permission) to the supported REST services. Each supported REST service is in its own servlet and shares a .WAR file with the other services.
Important: By default the REST services are configured in the Application Server Independent (ASI) node (Sterling B2B Integrator Java™ Virtual Machine). If the Sterling B2B Integrator REST services are not configured in the ASI node, you cannot find users in the Global Mailbox Management Tool, create event rules or view the Global Mailbox users on the Global Mailbox management tool. Therefore, it is suggested that you change the default settings of the REST services to point to the adapter container.

To establish a connection to the Global Mailbox system, Sterling B2B Integrator is registered with Global Mailbox by using the appConfigUtility during the installation. When registering Sterling B2B Integrator, the REST services are also registered with Global Mailbox. The registration is automated and does not require any manual intervention. However, if you need to change any parameters for user lookup or event data lookup, then you can run the following commands after installing Global Mailbox and Sterling B2B Integrator:

The following example illustrates appConfigUtility invocation for user lookup:
./appConfigUtility.sh setUserLookup --appID=<appID> --dcName=<datacenter name> --baseURL=https://si.myco.com:9876/api/V1 --authUser=gmbx_user --authPassword=password --removeURL=<URL>
appConfigUtility.bat setUserLookup --appID=<appID> --dcName=<datacenter name> --baseURL=https://si.myco.com:9876/api/V1 --authUser=gmbx_user --authPassword=password --removeURL=<URL>
The following example illustrates appConfigUtility invocation for event data lookup:
./appConfigUtility.sh setEventDataLookup --appID=<appID> --dcName=<datacenter name> --baseURL=https://si.myco.com:9876/api/V1 --authUser=gmbx_user --authPassword=password -removeURL=<URL>
appConfigUtility.bat setEventDataLookup --appID=<appID> --dcName=<datacenter name> --baseURL=https://si.myco.com:9876/api/V1 --authUser=gmbx_user --authPassword=password -removeURL=<URL>

To connect to Sterling B2B Integrator, and access the required resources through Global Mailbox REST Service adapter (of type HTTP Server adapter), Global Mailbox must have the following information. The installer configures the REST parameters during the installation.

Element Description Example
Request method The REST request method. Only GET is supported. GET
Host name The host where the Global Mailbox REST Services adapter instance (HTTP Server adapter type) is running. It is a Sterling B2B Integrator host. si.myco.com
Port The listening port of the Global Mailbox REST Services adapter. An appropriate port is configured by the Sterling B2B Integrator administrator. 9876
Resource path The REST resource path. It must start with /api/V1 /api/V1/users

/api/V1/event_properties/
User name User name for basic authentication. A new Sterling B2B Integrator user is supported. Any other user with permission corresponding to the specific REST API can also be used.
The gmbx_user user is granted the following permissions to execute the rest services:
  • Global Mailbox User Lookup REST API
  • Global Mailbox Event Property REST API
 gmbx_user
Password Password for basic authentication. The password is configured by the Sterling B2B Integrator administrator. password
Server certificate SSL certificate that represents the host Sterling B2B Integrator identity. Might be self-signed or signed by a certifying authority. The client (Global Mailbox) must be configured to trust this certificate as representing the server (Sterling B2B Integrator). Certificate file that is downloaded from Sterling B2B Integrator and associated with HTTPS Server adapter.
Important: The Global Mailbox REST Services adapter is preconfigured with appropriate resource path (.WAR file), URL, and a default port. If required, the Sterling B2B Integrator administrator can modify the following values:
  • Optionally change the port to a different value.
  • Change the certificate that is used for server authentication (default certificate is a self-signed certificate that is created during Sterling B2B Integrator installation. The default certificate is different for each Sterling B2B Integrator node.)
  • Enable the Global Mailbox REST Service adapter instance, as it is disabled by default.
The administrator must not modify the URL or the resource path.
The following Global Mailbox REST Services are currently supported:
  • User Lookup REST Service
  • Event Property REST Service
Note: If the auth password is modified using the command line in the setUserLookup utility, ensure you update the same in the setEventDataLookup utility. For example:
    
./appConfigUtility.sh setUserLookup --authPassword="newpc4us" --appName="B2Bi" --adminUser="admin" --adminPassword="password"

./appConfigUtility.sh setEventDataLookup --authPassword="newpc4us" --appName="B2Bi" --adminUser="admin" --adminPassword="password"

User Lookup REST Service

The User Lookup REST Service is hosted in the Global Mailbox REST Services adapter, and can be accessed from the URI /api/V1/users/. After successfully authenticating the user, the request returns a list of users who are in the Active state in Sterling B2B Integrator. If required, a Global Mailbox administrator can optionally choose to view Sterling B2B Integrator administrator users also.

Event Properties REST Service

The Event Properties REST Service is hosted in the Global Mailbox REST Services adapter, and can be accessed from the URI /api/V1/event_properties/. After successfully authenticating the user, the request returns a list of Sterling B2B Integrator supported event properties, such as, business process name, contract name, and user. By default, the service returns information on mandatory and invalid event property combinations. If required, the Global Mailbox administrator can initiate a second call to view the allowed values, for example, /api/V1/event_properties/BPNAME/allowed_values.