APX structure

An APX has the following attributes:

• APX type: Either Program APX (also called Script APX) or Web APX.
• APX unique name: This is the full name of the APX that must be unique. For example, com.hpe.sa.RestartMyApp.
• APX display name: This is usually a shorter name than the APX unique name. For example, RestartMyApp.
• APX version: You can maintain multiple versions of your APX by setting a version string or you can let SA manage versions for you automatically. The APX version can be a simple number such as version 1, 2, 3, and so on, or it can be any alphanumeric string.

See Importing an APX into SA - apxtool import and Setting the current version of an APX - apxtool setcurrent for more information.

File structure

To SA, an APX is just a set of files and directories that conform to the contract of the APX type (Program APX or Web APX) such that the APX runtime can properly execute it. For example, a Web APX may need an index.html file or an index.php file. A Program APX may require a shell command with the same name as the APX.

For more information on the files in an APX, see APX files.

OGFS integration

The APX infrastructure depends on the OGFS to manage user sessions and to expose various parts of the APX in the SA file system. The following sections describe how APX is integrated into the OGFS and its various applications.

APX Executable Directory

Program APXs are treated as executable programs in the Global Shell, OGSH. These APXs are exposed as an executable command in the OGSH. This allows a shell user to invoke the APX as if running a shell command.

The APX executable directory has the following format:

/opsw/apx/bin/{apx_name}

where apx_name is the name of the APX. Running apx_name in /opsw/apx/bin/{apx_name}invokes the current version of apx_name.

APX Runtime Directory

The APX Runtime directory is used by the APX runtime to support execution of an APX. The APX Runtime directory must have access to the APX source. In addition, users who have developer privileges and have read permission to an APX can also access the APX. The APX Runtime directory is not available for non-APX developers in the Global Shell.

The APX Runtime directory references the source of the current version of an APX. It has the format:

/opsw/apx/runtime/{apx_type}/{apx_name}

where apx_type can be script or web.

APX interfaces - Defining categories of APX extensions

APX interfaces enable you to create named categories of APXs and to find all the APXs of a given category. An interface is the name of the category. For example, you could create a category of APXs that all take a certain set of input parameters and produces a certain type of output data. Or you could create a category of APXs that all perform a specific set of operations.

You can also create an APX or an external application that gets the names of all APXs of the desired category and executes them. Or the APX or application could just present the list of APXs of the desired category and let the user select one to execute.

An APX interface is a name that defines an informal contract between the caller of an APX and the APX.

• An APX that defines an interface name creates a category of APX with that name.
• An APX that implements an interface declares itself to be an APX of that category.

A sample interface

SA provides an interface named RightClickToRun. This interface defines a category of APX that takes one or more devices as input parameters and runs against those devices. In addition, the SA Client displays all APXs that implement this interface in the Actions > Run Extension menu, which allows users to select one or more devices and run these APXs against the selected devices. For more information on this interface, see RightClickToRun interface.

Defining an interface

An APX interface defines the name of a category of APXs. All APXs that implement the interface belong to the category and must adhere to the conventions of the interface. To create a new category, you make your APX “define” the interface.

To make your APX define an interface, perform the following steps:

1. Create the APX with the apxtool new command. For details on this command, see Creating a new APX - apxtool new.
2. Locate the files of your new APX and open the file named interfaces in a text editor. The interfaces file is located in the APX-INF directory of your APX directory.
3. At the end of the interfaces file, add three lines for:
   • The name of the interface section in the file. This is the unique name of the interface.
   • The display name of the interface.
   • A description of the interface.

   For example, the following shows the interface section name, the display name and the description of the interface named “com.hpe.sa.MyNewInterface”:
   
   [com.hpe.sa.MyNewInterface]
name=MyNewInterface
description=”This is a simple interface for testing purposes.”

4. Save your changes and close the file.
5. Import your modified APX into SA with the apxtool import command. For details on this command, see Importing an APX into SA - apxtool import.

To upgrade an existing APX to define an interface you must create the interfaces file and add your interfaces as described above.

Implementing an interface

An APX interface specifies a category of APX that adheres to the conventions of the interface. To specify that your APX belongs to a category, you make your APX “implement” the interface. To make your APX implement an interface, perform the following steps.

1. Create the APX with the apxtool new command. For details on this command, see Creating a new APX - apxtool new.
2. Locate the files of your new APX and open the file named apx.cfg in a text editor.
3. Locate the section in your apx.cfg file that discusses the “Implementing” section. This section briefly describes how to specify the interfaces that your APX implements.
4. Locate the following lines in the file apx.cfg:
   
   [Implementing]
interfaces=
5. Modify the interfaces= line and add the name of your interface at the end of the line. For example, if your APX implements the interface named “com.hpe.sa.MyNewInterface”, the apx.cfg file would contain the following lines:
   
   [Implementing]
interfaces=com.hpe.sa.MyNewInterface
   
   To implement more than one interface, add them to the interfaces line separated by colon, as follows:
   
   [Implementing]
interfaces=com.hpe.sa.MyNewInterface:com.hpe.sa.AnotherInterface
6. Save your changes and close the file apx.cfg.
7. Import your modified APX into SA with the apxtool import command. For details on this command, see Importing an APX into SA - apxtool import.

You must set the current version of the APX to see the implemented interfaces when viewing the APX in the SA Client or with the apxtool query command. For more information, see Setting the current version of an APX - apxtool setcurrent.

To upgrade an existing APX to use an interface you must add your interfaces to your existing apx.cfg file as described above.

RightClickToRun interface

SA provides an interface you can use with your APXs named com.hpe.client.server.RightClickToRun. This interface works only with program APXs, not with web APXs. Use this interface when you want your APX to do all of the following:

• Take one or more devices as input parameters to the APX. APXs that implement this interface must take “-d <device id>” as an input argument.
• Appear in the Actions > Run Extension >Select Extension... window.
• Appear in the Actions > Run Extension menu of the SA Client. APXs appear in this menu after they have been run once using the Actions > Run Extension >Select Extension... menu.

To execute an APX from the Actions > Run Extension menu, the user must have execute permission on the APX. Any APX the user does not have permission to execute will not appear under this menu item. For information on permissions, see the Server Automation Administer section on the HPE SSO portal.

The RightClickToRun interface lets users select one or more devices in the SA Client and run your APX against those devices.

When you select the Actions > Run Extension menu item, the SA Client displays all of the program APXs that implement the interface com.hpe.client.server.RightClickToRun. When you select an APX, it is run against all the selected servers. The APX will be invoked once for each selected server.

For instructions on making your APX implement this interface, see Implementing an interface. For details on using an APX that implements this interface, see the Running SA Extensions section in the Server Automation Using Guide on the HPE SSO portal.

CoreAffinity interface

SA provides an interface that you can use with your APXs named ‘com.hpe.client.server.CoreAffinity’. You can use this interface when you want to run your APX in CoreAffinity mode.

CoreAffinity mode only applies when you have a mesh with at least two SA cores. When this mode is enabled for each target server, the APX is executed on the SA core to which this target server is registered, regardless of where the actual job was started.

For example:

• You have a mesh with two cores, core A and core B
• You start an APX job from core A on two target servers MA (registered to core A) and MB (registered to core B)

In core affinity mode this job runs the APX for MA on core A and MB on core B. If CoreAffinity is disabled then both executions will be done on core A (because that is where the job started).

For instructions on making your APX implement CoreAffinity interface, see Implementing an interface.

Using the Interface API

You can use the SA API to integrate your own applications with SA and APXs. Your application can determine all the APXs that implement a particular interface by using the interface named APXInterfaceService in the package named com.opsware.apx in the SA API. API Documentation and the Twister on using the SA API.