Getting Started with SAS Business Orchestration Services 10.2

[#1]

Introduction

SAS Business Orchestration Services is a highly customizable orchestration framework that helps you integrate multiple systems quickly and easily.  Its features enable you to implement enterprise integration patterns of varying complexity using a set of high-level abstractions that require minimal coding. This allows you to focus on what needs to be done, rather than how. 

SAS Business Orchestration Services enables you to complete the following:

• achieve quick integration and a loose coupling of systems in your organization with minimal overhead and latency
• integrate newer tools, technologies, and systems into your organization easily so that the software systems that support your business can evolve at the pace of your business
• optimize the flow of data between systems

SAS Business Orchestration Services uses Apache Camel as its execution engine. Therefore, communications between systems is achieved using routes (and endpoints as inputs and outputs to routes) to define the step-by-step transformation, enrichment, and movement of data. This article walks you through the SAS Business Orchestration Services installation process. Then it provides sample routes to get you started and on your way to creating your own Camel routes that meet your specific integration needs.

Installing SAS Business Orchestration Services

Before you begin the installation process, you need access to the SAS Business Orchestration Services RPM file called 
sas-boss-<version>-<build-date>.<build-ID>.x84_64.rpm and the corresponding license file. If you do not have access to these files, contact your SAS site representative. They will have a software order email that contains instructions on how to obtain the necessary RPM and license files.

To install SAS Business Orchestration Services, run the following command with sudo privileges:

rpm -ivh /<path-to-rpm file>/sas-boss-<version>-<build-date>.<build-ID>.x86_64.rpm

For more information about installing SAS Business Orchestration Services, see "Install SAS Business Orchestration Services" in SAS® Business Orchestration Services 10.2: Deployment Guide

This command installs the SAS Business Orchestration Services files and creates the following directory structure:

SAS Business Orchestration Services Location	Description
/opt/sas/viya/home/bin/boss	Contains all executable scripts that come with SAS Business Orchestration Services including the boss.sh script that is used to start and stop SAS Business Orchestration Services and to check its status.
/opt/sas/viya/home/libexec/boss	Contains the core SAS Business Orchestration Services executable (springboot) JAR file.
/opt/sas/viya/home/lib/boss	Contains additional JAR files for SAS Business Orchestration Services components such as third-party adapters or SAS OnDemand Decision Engine scoring. For more information, see the SAS® OnDemand Decision Engine: System Administrator's Guide.
/opt/sas/viya/config/etc/boss	The base folder for all SAS Business Orchestration Services configuration files. Initially, this directory contains only an empty lib folder, but it is where you will put the license file, properties file, and other files that define your various routes.
/opt/sas/viya/config/var/log/boss	Contains the logs associated with SAS Business Orchestration Services, including the boss.log and the application.log files.   Typically, boss.log contains logging information related to the startup of SAS Business Orchestration Services and application.log contains logging information related to route configuration.
/opt/sas/viya/home/share/boss	Contains example configuration files that are delivered with SAS Business Orchestration Services third-party adapters. The examples are installed when you order a particular adapter.

When the directory structure has been laid down, it is owned by the sas user ID and the sas group.  If you want to use a user ID other than sas to manage SAS Business Orchestration Services, you must add that user ID to the sas user group. 

For more information, see "Key Folders and Files" in SAS® Business Orchestration Services 10.2: User’s Guide .

Installing the License File

Now that you have successfully installed SAS Business Orchestration Services, copy your license file into the configuration directory and rename it to setinit.txt.

To do so, you can run the following command:

cp <location-of-license-file> /opt/sas/viya/config/etc/boss/setinit.txt

Starting SAS Business Orchestration Services for the First Time

Once your license file is in place, start SAS Business Orchestration Services by running the following command:

/opt/sas/viya/home/bin/boss/boss.sh start

This command outputs a list of SAS Business Orchestration Services environment variables followed by a Starting BOSS message. After waiting a few seconds, confirm that SAS Business Orchestration Services started successfully by running the following command:

/opt/sas/viya/home/bin/boss/boss.sh status

This command should return a  "BOSS is running. Process ID: nnnnnn"  message.  If it does not, then check the two SAS Business Orchestration Services log files for start up problems:

/opt/sas/viya/config/var/log/boss/boss.log

/opt/sas/viya/config/var/log/boss/application.log

To see what is going on behind the scenes when SAS Business Orchestration Services starts, open the application.log file. In the last lines of the  application.log file you should see messages similar to the ones below.  Lines at the beginning of the application.log file are typical Camel start-up messages that can be ignored for now. 

Note: In the following example, the date and time line prefix has been removed for readability. 

INFO 4332 --- [main] o.a.c.i.e.InternalRouteStartupManager : Route: startupLogger started and consuming from: timer://startupLogger
INFO 4332 --- [main] o.a.c.impl.engine.AbstractCamelContext : Total 1 routes, of which 1 are started
INFO 4332 --- [main] o.a.c.impl.engine.AbstractCamelContext : Apache Camel 3.4.4 (default) started in 0.239 seconds
INFO 4332 --- [Camel (default) thread #1 - timer://startupLogger] startup : SAS Business Orchestration Services started

Looking at the log lines above, notice that SAS Business Orchestration Services ships with a simple internal Camel route named startupLogger. This route consumes from the Camel timer component such that it runs once upon start up. The route writes a message, " SAS Business Orchestration Services started,"  to the log to show that SAS Business Orchestration Services started successfully. 

For more information about starting and stopping SAS Business Orchestration Services, see "Life-Cycle Commands" in SAS® Business Orchestration Services 10.2: User’s Guide.

Creating Your First Camel Route

Now that you have confirmed that SAS Business Orchestration Services starts successfully, it is time to create your own simple Camel route that writes "Hello World!" to the application.log file. 

1. Navigate to the /opt/sas/viya/config/etc/boss/ directory.
2. Use the following command to create a routes directory:
   mkdir routes
3. In the routes directory, create a new file named hello-world.xml and save the following text in the file:

<?xml version="1.0" encoding="UTF-8"?>
<routes xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="timer://sayHello?repeatCount=2"/>
        <log message="Hello World!"/>
    </route>
</routes>

This file creates one route that is started the next time that SAS Business Orchestration Services starts. (Upon startup, SAS Business Orchestration Services looks in the  /opt/sas/viya/config/etc/boss/routes directory and starts all routes it finds there.) 
Line 4 in the route uses the  Camel Timer component  to create a timer called sayHello. When the timer fires, Line 5 writes an entry in the application.log file.

To see this new route in action, stop and restart SAS Business Orchestration Services. Then open the application.log file. At the end of the log file, you should see lines similar to the following:

INFO 160811 --- [main] o.a.c.i.e.InternalRouteStartupManager : Route: startupLogger started and consuming from: timer://startupLogger
INFO 160811 --- [main] o.a.c.i.e.InternalRouteStartupManager : Route: route1 started and consuming from: timer://sayHello
INFO 160811 --- [main] o.a.c.impl.engine.AbstractCamelContext : Total 2 routes, of which 2 are started
INFO 160811 --- [main] o.a.c.impl.engine.AbstractCamelContext : Apache Camel 3.4.4 (default) started in 0.115 seconds
INFO 160811 --- [Camel (default) thread #2 - timer://sayHello] route1 : Hello World!
INFO 160811 --- [Camel (default) thread #2 - timer://sayHello] route1 : Hello World!
INFO 160811 --- [Camel (default) thread #1 - timer://startupLogger] startup : SAS Business Orchestration Services started

This time, notice the following:

• Two routes started: the built-in route named startupLogger that you saw in the previous section and your new route.
• Because you did not specify a name for your route, Camel gave it a generic name, route1. 
• Because you configured the timer component with a repeatCount=2, the route runs twice and therefore you see two "Hello World!" log messages.
• SAS Business Orchestration Services appends to the  application.log file when it restarts. If you want a clean log, delete or rename the application.log file between restarts.

Want more? To experiment, try modifying the hello-world.xml file. Restart SAS Business Orchestration Services to see the new behavior. Here are some suggestions to try:

• Name your route by supplying the id attribute (for example, <route id = "myRoute">).
• Change or add options to the Camel Timer component to change its behavior (for example, uri="timer://sayHello?repeatCount=5&amp;delay=60").
• Create another route in the same file by copying lines 3-6 and changing the route id and the log message.

 

Creating Your First REST Endpoint 

In the following example, you will define a simple REST service that responds with a personalized greeting. You can call your REST endpoint using either a curl command or a web browser invocation.  In this example, you will use the curl command.

To set up this example, you will create the following three files:

• An XML file that defines a REST API endpoint.
• A properties file to configure the port for REST endpoints.
• An XML file that defines a route that is run when the REST API endpoint is called.

To create the REST file, complete the following:

1. Navigate to the /opt/sas/viya/config/etc/boss/ directory.
2. Use the following command to create a rest directory:
   mkdir rest
3. In the rest directory, create a new file named greet-rest.xml and save the following text in the file:

<?xml version="1.0" encoding="UTF-8"?>
<rests xmlns="http://camel.apache.org/schema/spring">
    <rest path="/greet/{name}">
        <get>
            <to uri="direct:greet"/>
        </get>
    </rest>
</rests>

This file uses the Camel REST Component to define a REST endpoint. Line 3 creates the endpoint with a base path of /greet/{name} where name is a placeholder. Line 3, in conjunction with the port value set in the application.properties file, defines the URL to the endpoint. (See the curl command below for a complete URL.) Line 5 uses the Camel Direct component to invoke a route named greet when the REST endpoint receives a GET request. 

To create the properties file, complete the following:

1. Navigate to the /opt/sas/viya/config/etc/boss directory.
2. In the boss directory, create a new file named application.properties and save the following text in the file: 
   camel.rest.port=8080

To create the route XML file, complete the following:

1. Navigate to the /opt/sas/viya/config/etc/boss/routes directory.
2. In the routes directory, create a new file named greet-route.xml and save the following text in the file:

<?xml version="1.0" encoding="UTF-8"?>
<routes xmlns="http://camel.apache.org/schema/spring">
    <route id="myGreeting">
        <from uri="direct:greet"/>
        <setBody>
            <simple>Hello, ${header.name}, how are you doing today?\n</simple>
        </setBody>
    </route>
</routes>

This file creates a route named myGreeting. Line 4 uses the Camel Direct component to indicate that this route can be invoked synchronously. When this route is called, Line 6 sets the response body to the greeting string using the Camel Simple Expression Language. Note that${header.name} is the value provided in your REST endpoint URL and is used in the greeting string.  (All placeholders in a URL for REST API endpoints are accessible as message headers.)

To see this new REST service in action, stop and restart SAS Business Orchestration Services. Invoke the following curl command in the Linux command prompt:

curl http://localhost:8080/greet/John 

This command returns the following response:

Hello, John, how are you doing today?

Look at the application.log file. At the end of the log file, you should see lines similar to the following:

INFO 166091 --- [main] o.a.c.i.e.InternalRouteStartupManager : Route: startupLogger started and consuming from: timer://startupLogger
INFO 166091 --- [main] o.a.c.i.e.InternalRouteStartupManager : Route: myGreeting started and consuming from: direct://greet
INFO 166091 --- [main] o.a.c.i.e.InternalRouteStartupManager : Route: route1 started and consuming from: timer://sayHello
INFO 166091 --- [main] org.eclipse.jetty.util.log : Logging initialized @9739ms to org.eclipse.jetty.util.log.Slf4jLog
INFO 166091 --- [main] org.eclipse.jetty.server.Server : jetty-9.4.39.v20210325; built: 2021-03-25T14:42:11.471Z; git: 9fc7ca5a922f2a37b84ec9dbc26a5168cee7e667; jvm 1.8.0_282-b08
INFO 166091 --- [main] o.e.jetty.server.handler.ContextHandler : Started o.e.j.s.ServletContextHandler@591fd34d{/,null,AVAILABLE}
INFO 166091 --- [main] o.e.jetty.server.AbstractConnector : Started ServerConnector@57bd2029{HTTP/1.1, (http/1.1)}{0.0.0.0:44164}
INFO 166091 --- [main] org.eclipse.jetty.server.Server : Started @9915ms
INFO 166091 --- [main] o.a.c.i.e.InternalRouteStartupManager : Route: route2 started and consuming from: jetty:http://0.0.0.0:8080/greet/%7Bname%7D
INFO 166091 --- [main] o.a.c.impl.engine.AbstractCamelContext : Total 4 routes, of which 4 are started
INFO 166091 --- [main] o.a.c.impl.engine.AbstractCamelContext : Apache Camel 3.4.4 (default) started in 0.346 seconds
INFO 166091 --- [Camel (default) thread #2 - timer://sayHello] route1 : Hello World!
INFO 166091 --- [Camel (default) thread #2 - timer://sayHello] route1 : Hello World!
INFO 166091 --- [Camel (default) thread #1 - timer://startupLogger] startup : SAS Business Orchestration Services started

This time, notice the following:

• Four routes started.
• The two routes that were discussed in the previous examples are started in Lines 1 and Line 3.
• The two new routes that make up this REST service example are started in Line 2 and Line 9. 
• Line 9 provides the URL of the REST endpoint and indicates that it is listening  on the  0.0.0.0  (localhost) host name on port 8080.
• SAS Business Orchestration Services uses the Camel jetty component for REST endpoints, so lines 4-8 are typical Camel startup messages for jetty that can be ignored for now.

Additional Resources

You are now ready to create your own Camel routes to use with SAS Business Orchestration Services. For more information about how to customize your SAS Business Orchestration Services environment and create additional Camel routes, see the following resources:

SAS® Business Orchestration Services 10.2 User’s Guide

Camel Documentation: Components